![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to emacs.tex CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / contrib / emacs-18.55 / man|
Return to emacs.tex CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / emacs-18.55 / man |
1.1 ! root 1: \input texinfo @c -*-texinfo-*- ! 2: @setfilename ../info/emacs ! 3: @c @smallbook ! 4: @tex ! 5: \overfullrule=0pt ! 6: @end tex ! 7: @ifinfo ! 8: This file documents the GNU Emacs editor. ! 9: ! 10: Copyright (C) 1985, 1986 Richard M. Stallman. ! 11: ! 12: Permission is granted to make and distribute verbatim copies of ! 13: this manual provided the copyright notice and this permission notice ! 14: are preserved on all copies. ! 15: ! 16: @ignore ! 17: Permission is granted to process this file through Tex and print the ! 18: results, provided the printed document carries copying permission ! 19: notice identical to this one except for the removal of this paragraph ! 20: (this paragraph not being relevant to the printed manual). ! 21: ! 22: @end ignore ! 23: Permission is granted to copy and distribute modified versions of this ! 24: manual under the conditions for verbatim copying, provided also that the ! 25: sections entitled ``The GNU Manifesto'', ``Distribution'' and ``GNU Emacs ! 26: General Public License'' are included exactly as in the original, and ! 27: provided that the entire resulting derived work is distributed under the ! 28: terms of a permission notice identical to this one. ! 29: ! 30: Permission is granted to copy and distribute translations of this manual ! 31: into another language, under the above conditions for modified versions, ! 32: except that the sections entitled ``The GNU Manifesto'', ``Distribution'' ! 33: and ``GNU Emacs General Public License'' may be included in a translation ! 34: approved by the author instead of in the original English. ! 35: @end ifinfo ! 36: @c ! 37: @setchapternewpage odd ! 38: @settitle GNU Emacs Manual ! 39: @c ! 40: @titlepage ! 41: @sp 6 ! 42: @center @titlefont{GNU Emacs Manual} ! 43: @sp 4 ! 44: @center Fifth Edition, Emacs Version 18 ! 45: @sp 1 ! 46: @center for Unix Users ! 47: @sp 1 ! 48: @center October 1986 ! 49: @sp 5 ! 50: @center Richard Stallman ! 51: @page ! 52: @vskip 0pt plus 1filll ! 53: Copyright @copyright{} 1985, 1986 Richard M. Stallman. ! 54: ! 55: Permission is granted to make and distribute verbatim copies of ! 56: this manual provided the copyright notice and this permission notice ! 57: are preserved on all copies. ! 58: ! 59: Permission is granted to copy and distribute modified versions of this ! 60: manual under the conditions for verbatim copying, provided also that the ! 61: sections entitled ``The GNU Manifesto'', ``Distribution'' and ``GNU Emacs ! 62: General Public License'' are included exactly as in the original, and ! 63: provided that the entire resulting derived work is distributed under the ! 64: terms of a permission notice identical to this one. ! 65: ! 66: Permission is granted to copy and distribute translations of this manual ! 67: into another language, under the above conditions for modified versions, ! 68: except that the sections entitled ``The GNU Manifesto'', ``Distribution'' ! 69: and ``GNU Emacs General Public License'' may be included in a translation ! 70: approved by the author instead of in the original English. ! 71: @end titlepage ! 72: @page ! 73: @ifinfo ! 74: @node Top, Distrib,, (DIR) ! 75: ! 76: The Emacs Editor ! 77: **************** ! 78: ! 79: Emacs is the extensible, customizable, self-documenting real-time ! 80: display editor. This Info file describes how to edit with Emacs ! 81: and some of how to customize it, but not how to extend it. ! 82: ! 83: @end ifinfo ! 84: @menu ! 85: * Distrib:: How to get the latest Emacs distribution. ! 86: * License:: The GNU Emacs General Public License gives you permission ! 87: to redistribute GNU Emacs on certain terms; and also ! 88: explains that there is no warranty. ! 89: * Intro:: An introduction to Emacs concepts. ! 90: * Glossary:: The glossary. ! 91: * Manifesto:: What's GNU? Gnu's Not Unix! ! 92: ! 93: Indexes, nodes containing large menus ! 94: * Key Index:: An item for each standard Emacs key sequence. ! 95: * Command Index:: An item for each command name. ! 96: * Variable Index:: An item for each documented variable. ! 97: * Concept Index:: An item for each concept. ! 98: ! 99: Important General Concepts ! 100: * Screen:: How to interpret what you see on the screen. ! 101: * Characters:: Emacs's character sets for file contents and for keyboard. ! 102: * Keys:: Key sequences: what you type to request one editing action. ! 103: * Commands:: Commands: named functions run by key sequences to do editing. ! 104: * Entering Emacs:: Starting Emacs from the shell. ! 105: * Command Switches:: Hairy startup options. ! 106: * Exiting:: Stopping or killing Emacs. ! 107: * Basic:: The most basic editing commands. ! 108: * Undo:: Undoing recently made changes in the text. ! 109: * Minibuffer:: Entering arguments that are prompted for. ! 110: * M-x:: Invoking commands by their names. ! 111: * Help:: Commands for asking Emacs about its commands. ! 112: ! 113: Important Text-Changing Commands ! 114: * Mark:: The mark: how to delimit a ``region'' of text. ! 115: * Killing:: Killing text. ! 116: * Yanking:: Recovering killed text. Moving text. ! 117: * Accumulating Text:: ! 118: Other ways of copying text. ! 119: * Rectangles:: Operating on the text inside a rectangle on the screen. ! 120: * Registers:: Saving a text string or a location in the buffer. ! 121: * Display:: Controlling what text is displayed. ! 122: * Search:: Finding or replacing occurrences of a string. ! 123: * Fixit:: Commands especially useful for fixing typos. ! 124: ! 125: Larger Units of Text ! 126: * Files:: All about handling files. ! 127: * Buffers:: Multiple buffers; editing several files at once. ! 128: * Windows:: Viewing two pieces of text at once. ! 129: ! 130: Advanced Features ! 131: * Major Modes:: Text mode vs. Lisp mode vs. C mode ... ! 132: * Indentation:: Editing the white space at the beginnings of lines. ! 133: * Text:: Commands and modes for editing English. ! 134: * Programs:: Commands and modes for editing programs. ! 135: * Running:: Compiling, running and debugging programs. ! 136: * Abbrevs:: How to define text abbreviations to reduce ! 137: the number of characters you must type. ! 138: * Picture:: Editing pictures made up of characters ! 139: using the quarter-plane screen model. ! 140: * Sending Mail::Sending mail in Emacs. ! 141: * Rmail:: Reading mail in Emacs. ! 142: * Recursive Edit:: ! 143: A command can allow you to do editing ! 144: "within the command". This is called a ! 145: `recursive editing level'. ! 146: * Narrowing:: Restricting display and editing to a portion ! 147: of the buffer. ! 148: * Sorting:: Sorting lines, paragraphs or pages within Emacs. ! 149: * Shell:: Executing shell commands from Emacs. ! 150: * Hardcopy:: Printing buffers or regions. ! 151: * Dissociated Press:: Dissociating text for fun. ! 152: * Amusements:: Various games and hacks. ! 153: * Emulation:: Emulating some other editors with Emacs. ! 154: * Customization:: Modifying the behavior of Emacs. ! 155: ! 156: Recovery from Problems. ! 157: * Quitting:: Quitting and aborting. ! 158: * Lossage:: What to do if Emacs is hung or malfunctioning. ! 159: * Bugs:: How and when to report a bug. ! 160: ! 161: Here are some other nodes which are really inferiors of the ones ! 162: already listed, mentioned here so you can get to them in one step: ! 163: ! 164: Subnodes of Screen ! 165: * Point:: The place in the text where editing commands operate. ! 166: * Echo Area:: Short messages appear at the bottom of the screen. ! 167: * Mode Line:: Interpreting the mode line. ! 168: ! 169: Subnodes of Basic ! 170: * Blank Lines:: Commands to make or delete blank lines. ! 171: * Continuation Lines:: Lines too wide for the screen. ! 172: * Position Info:: What page, line, row, or column is point on? ! 173: * Arguments:: Giving numeric arguments to commands. ! 174: ! 175: Subnodes of Minibuffer ! 176: * Minibuffer File:: Entering file names with the minibuffer. ! 177: * Minibuffer Edit:: How to edit in the minibuffer. ! 178: * Completion:: An abbreviation facility for minibuffer input. ! 179: * Repetition:: Re-executing previous commands that used the minibuffer. ! 180: ! 181: Subnodes of Mark ! 182: * Setting Mark:: Commands to set the mark. ! 183: * Using Region:: Summary of ways to operate on contents of the region. ! 184: * Marking Objects:: Commands to put region around textual units. ! 185: * Mark Ring:: Previous mark positions saved so you can go back there. ! 186: ! 187: Subnodes of Yanking ! 188: * Kill Ring:: Where killed text is stored. Basic yanking. ! 189: * Appending Kills:: Several kills in a row all yank together. ! 190: * Earlier Kills:: Yanking something killed some time ago. ! 191: ! 192: Subnodes of Registers ! 193: * RegPos:: Saving positions in registers. ! 194: * RegText:: Saving text in registers. ! 195: * RegRect:: Saving rectangles in registers. ! 196: ! 197: Subnodes of Display ! 198: * Scrolling:: Moving text up and down in a window. ! 199: * Horizontal Scrolling:: Moving text left and right in a window. ! 200: * Selective Display:: Hiding lines with lots of indentation. ! 201: * Display Vars:: Information on variables for customizing display. ! 202: ! 203: Subnodes of Search ! 204: * Incremental Search:: Search happens as you type the string. ! 205: * Nonincremental Search:: Specify entire string and then search. ! 206: * Word Search:: Search for sequence of words. ! 207: * Regexp Search:: Search for match for a regexp. ! 208: * Regexps:: Syntax of regular expressions. ! 209: * Search Case:: To ignore case while searching, or not. ! 210: * Replace:: Search, and replace some or all matches. ! 211: * Unconditional Replace:: Everything about replacement except for querying. ! 212: * Query Replace:: How to use querying. ! 213: * Other Repeating Search:: Operating on all matches for some regexp. ! 214: ! 215: Subnodes of Fixit ! 216: * Kill Errors:: Commands to kill a batch of recently entered text. ! 217: * Transpose:: Exchanging two characters, words, lines, lists... ! 218: * Fixing Case:: Correcting case of last word entered. ! 219: * Spelling:: Apply spelling checker to a word, or a whole file. ! 220: ! 221: Subnodes of Files ! 222: * File Names:: How to type and edit file name arguments. ! 223: * Visiting:: Visiting a file prepares Emacs to edit the file. ! 224: * Saving:: Saving makes your changes permanent. ! 225: * Backup:: How Emacs saves the old version of your file. ! 226: * Interlocking::How Emacs protects against simultaneous editing ! 227: of one file by two users. ! 228: * Reverting:: Reverting cancels all the changes not saved. ! 229: * Auto Save:: Auto Save periodically protects against loss of data. ! 230: * ListDir:: Listing the contents of a file directory. ! 231: * Dired:: ``Editing'' a directory to delete, rename, etc. ! 232: the files in it. ! 233: * Misc File Ops:: Other things you can do on files. ! 234: ! 235: Subnodes of Buffers ! 236: * Select Buffer:: Creating a new buffer or reselecting an old one. ! 237: * List Buffers:: Getting a list of buffers that exist. ! 238: * Misc Buffer:: Renaming; changing read-only status. ! 239: * Kill Buffer:: Killing buffers you no longer need. ! 240: * Several Buffers:: How to go through the list of all buffers ! 241: and operate variously on several of them. ! 242: ! 243: Subnodes of Windows ! 244: * Basic Window:: Introduction to Emacs windows. ! 245: * Split Window:: New windows are made by splitting existing windows. ! 246: * Other Window:: Moving to another window or doing something to it. ! 247: * Pop Up Window:: Finding a file or buffer in another window. ! 248: * Change Window:: Deleting windows and changing their sizes. ! 249: ! 250: Subnodes of Indentation ! 251: * Indentation Commands:: Various commands and techniques for indentation. ! 252: * Tab Stops:: You can set arbitrary "tab stops" and then ! 253: indent to the next tab stop when you want to. ! 254: * Just Spaces:: You can request indentation using just spaces. ! 255: ! 256: Subnodes of Text ! 257: * Text Mode:: The major mode for editing text files. ! 258: * Nroff Mode:: The major mode for editing input to the formatter nroff. ! 259: * TeX Mode:: The major mode for editing input to the formatter TeX. ! 260: * Outline Mode::The major mode for editing outlines. ! 261: * Words:: Moving over and killing words. ! 262: * Sentences:: Moving over and killing sentences. ! 263: * Paragraphs:: Moving over paragraphs. ! 264: * Pages:: Moving over pages. ! 265: * Filling:: Filling or justifying text ! 266: * Case:: Changing the case of text ! 267: ! 268: Subnodes of Programs ! 269: * Program Modes:: Major modes for editing programs. ! 270: * Lists:: Expressions with balanced parentheses. ! 271: There are editing commands to operate on them. ! 272: * Defuns:: Each program is made up of separate functions. ! 273: There are editing commands to operate on them. ! 274: * Grinding:: Adjusting indentation to show the nesting. ! 275: * Matching:: Insertion of a close-delimiter flashes matching open. ! 276: * Comments:: Inserting, illing and aligning comments. ! 277: * Balanced Editing:: Inserting two matching parentheses at once, etc. ! 278: * Lisp Completion:: Completion on symbol names in Lisp code. ! 279: * Documentation:: Getting documentation of functions you plan to call. ! 280: * Change Log:: Maintaining a change history for your program. ! 281: * Tags:: Go direct to any function in your program in one ! 282: command. Tags remembers which file it is in. ! 283: * Fortran:: Fortran mode and its special features. ! 284: ! 285: Subnodes of Running ! 286: * Compilation:: Compiling programs in languages other than Lisp ! 287: (C, Pascal, etc.) ! 288: * Lisp Modes:: Various modes for editing Lisp programs, with ! 289: different facilities for running the Lisp programs. ! 290: * Lisp Libraries:: Creating Lisp programs to run in Emacs. ! 291: * Lisp Interaction:: Executing Lisp in an Emacs buffer. ! 292: * Lisp Eval:: Executing a single Lisp expression in Emacs. ! 293: * Lisp Debug:: Debugging Lisp programs running in Emacs. ! 294: * External Lisp:: Communicating through Emacs with a separate Lisp. ! 295: ! 296: Subnodes of Abbrevs ! 297: * Defining Abbrevs:: Defining an abbrev, so it will expand when typed. ! 298: * Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion. ! 299: * Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs. ! 300: * Saving Abbrevs:: Saving the entire list of abbrevs for another session. ! 301: * Dynamic Abbrevs:: Abbreviations for words already in the buffer. ! 302: ! 303: Subnodes of Picture ! 304: * Basic Picture:: Basic concepts and simple commands of Picture Mode. ! 305: * Insert in Picture:: Controlling direction of cursor motion ! 306: after "self-inserting" characters. ! 307: * Tabs in Picture:: Various features for tab stops and indentation. ! 308: * Rectangles in Picture:: Clearing and superimposing rectangles. ! 309: ! 310: Subnodes of Sending Mail ! 311: * Mail Format:: Format of the mail being composed. ! 312: * Mail Headers:: Details of allowed mail header fields. ! 313: * Mail Mode:: Special commands for editing mail being composed. ! 314: ! 315: Subnodes of Rmail ! 316: * Rmail Scrolling:: Scrolling through a message. ! 317: * Rmail Motion:: Moving to another message. ! 318: * Rmail Deletion:: Deleting and expunging messages. ! 319: * Rmail Inbox:: How mail gets into the Rmail file. ! 320: * Rmail Files:: Using multiple Rmail files. ! 321: * Rmail Output:: Copying message out to files. ! 322: * Rmail Labels:: Classifying messages by labeling them. ! 323: * Rmail Summary:: Summaries show brief info on many messages. ! 324: * Rmail Reply:: Sending replies to messages you are viewing. ! 325: * Rmail Editing:: Editing message text and headers in Rmail. ! 326: * Rmail Digest:: Extracting the messages from a digest message. ! 327: ! 328: Subnodes of Shell ! 329: * Single Shell:: Commands to run one shell command and return. ! 330: * Interactive Shell:: Permanent shell taking input via Emacs. ! 331: * Shell Mode:: Special Emacs commands used with permanent shell. ! 332: ! 333: Subnodes of Customization ! 334: * Minor Modes:: Each minor mode is one feature you can turn on ! 335: independently of any others. ! 336: * Variables:: Many Emacs commands examine Emacs variables ! 337: to decide what to do; by setting variables, ! 338: you can control their functioning. ! 339: * Examining:: Examining or setting one variable's value. ! 340: * Edit Options:: Examining or editing list of all variables' values. ! 341: * Locals:: Per-buffer values of variables. ! 342: * File Variables:: How files can specify variable values. ! 343: * Keyboard Macros:: A keyboard macro records a sequence of keystrokes ! 344: to be replayed with a single command. ! 345: * Key Bindings:: The keymaps say what command each key runs. ! 346: By changing them, you can "redefine keys". ! 347: * Keymaps:: Definition of the keymap data structure. ! 348: * Rebinding:: How to redefine one key's meaning conveniently. ! 349: * Disabling:: Disabling a command means confirmation is required ! 350: before it can be executed. This is done to protect ! 351: beginners from surprises. ! 352: * Syntax:: The syntax table controls how words and expressions ! 353: are parsed. ! 354: * Init File:: How to write common customizations in the `.emacs' file. ! 355: ! 356: Subnodes of Lossage (and recovery) ! 357: * Stuck Recursive:: `[...]' in mode line around the parentheses. ! 358: * Screen Garbled:: Garbage on the screen. ! 359: * Text Garbled:: Garbage in the text. ! 360: * Unasked-for Search::Spontaneous entry to incremental search. ! 361: * Emergency Escape:: Emergency escape--- ! 362: What to do if Emacs stops responding. ! 363: * Total Frustration:: When you are at your wits' end. ! 364: @end menu ! 365: ! 366: @iftex ! 367: @unnumbered Preface ! 368: ! 369: This manual documents the use and simple customization of the ! 370: Emacs editor. The reader is not expected to be a programmer. Even simple ! 371: customizations do not require programming skill, but the user who is not ! 372: interested in customizing can ignore the scattered customization hints. ! 373: ! 374: This is primarily a reference manual, but can also be used as a ! 375: primer. However, I recommend that the newcomer first use the on-line, ! 376: learn-by-doing tutorial, which you get by running Emacs and typing ! 377: @kbd{C-h t}. With it, you learn Emacs by using Emacs on a specially ! 378: designed file which describes commands, tells you when to try them, ! 379: and then explains the results you see. This gives a more vivid ! 380: introduction than a printed manual. ! 381: ! 382: On first reading, just skim chapters one and two, which describe the ! 383: notational conventions of the manual and the general appearance of the ! 384: Emacs display screen. Note which questions are answered in these chapters, ! 385: so you can refer back later. After reading chapter four you should ! 386: practice the commands there. The next few chapters describe fundamental ! 387: techniques and concepts that are used constantly. You need to understand ! 388: them thoroughly, experimenting with them if necessary. ! 389: ! 390: To find the documentation on a particular command, look in the index. ! 391: Keys (character commands) and command names have separate indexes. There ! 392: is also a glossary, with a cross reference for each term. ! 393: ! 394: @ignore ! 395: If you know vaguely what the command ! 396: does, look in the command summary. The command summary contains a line or ! 397: two about each command, and a cross reference to the section of the ! 398: manual that describes the command in more detail; related commands ! 399: are grouped together. ! 400: @end ignore ! 401: ! 402: This manual comes in two forms: the published form and the Info form. ! 403: The Info form is for on-line perusal with the INFO program; it is ! 404: distributed along with GNU Emacs. Both forms contain substantially the ! 405: same text and are generated from a common source file, which is also ! 406: distributed along with GNU Emacs. ! 407: ! 408: GNU Emacs is a member of the Emacs editor family. There are many Emacs ! 409: editors, all sharing common principles of organization. For information on ! 410: the underlying philosophy of Emacs and the lessons learned from its ! 411: development, write for a copy of AI memo 519a, ``Emacs, the Extensible, ! 412: Customizable Self-Documenting Display Editor'', to Publications Department, ! 413: Artificial Intelligence Lab, 545 Tech Square, Cambridge, MA 02139, USA. At ! 414: last report they charge $2.25 per copy. Another useful publication is LCS ! 415: TM-165, ``A Cookbook for an Emacs'', by Craig Finseth, available from ! 416: Publications Department, Laboratory for Computer Science, 545 Tech Square, ! 417: Cambridge, MA 02139, USA. The price today is $3. ! 418: ! 419: This edition of the manual is intended for use with GNU Emacs installed on ! 420: Unix systems. GNU Emacs can also be used on VMS systems, which have ! 421: different file name syntax and do not support all GNU Emacs features. A ! 422: VMS edition of this manual may appear in the future. ! 423: @end iftex ! 424: ! 425: @node Distrib, License, Top, Top ! 426: @unnumbered Distribution ! 427: ! 428: GNU Emacs is @dfn{free}; this means that everyone is free to use it and ! 429: free to redistribute it on a free basis. GNU Emacs is not in the public ! 430: domain; it is copyrighted and there are restrictions on its distribution, ! 431: but these restrictions are designed to permit everything that a good ! 432: cooperating citizen would want to do. What is not allowed is to try to ! 433: prevent others from further sharing any version of GNU Emacs that they ! 434: might get from you. The precise conditions are found in the GNU Emacs ! 435: General Public License that comes with Emacs and also appears following ! 436: this section. ! 437: ! 438: The easiest way to get a copy of GNU Emacs is from someone else who has it. ! 439: You need not ask for permission to do so, or tell any one else; just copy ! 440: it. ! 441: ! 442: If you have access to the Internet, you can get the latest distribution ! 443: version of GNU Emacs from host @file{prep.ai.mit.edu} using anonymous ! 444: login. See the file @file{/u2/emacs/GETTING.GNU.SOFTWARE} on that host ! 445: to find out about your options for copying and which files to use. ! 446: ! 447: You may also receive GNU Emacs when you buy a computer. Computer ! 448: manufacturers are free to distribute copies on the same terms that apply to ! 449: everyone else. These terms require them to give you the full sources, ! 450: including whatever changes they may have made, and to permit you to ! 451: redistribute the GNU Emacs received from them under the usual terms of the ! 452: General Public License. In other words, the program must be free for you ! 453: when you get it, not just free for the manufacturer. ! 454: ! 455: If you cannot get a copy in any of those ways, you can order one from the ! 456: Free Software Foundation. Though Emacs itself is free, our distribution ! 457: service is not. An order form is included at the end of manuals printed by ! 458: the Foundation. It is also included in the file @file{etc/DISTRIB} in the ! 459: Emacs distribution. For further information, write to ! 460: ! 461: @display ! 462: Free Software Foundation ! 463: 675 Mass Ave ! 464: Cambridge, MA 02139 ! 465: USA ! 466: @end display ! 467: ! 468: The income from distribution fees goes to support the foundation's ! 469: purpose: the development of more free software to distribute just like ! 470: GNU Emacs. ! 471: ! 472: If you find GNU Emacs useful, please @b{send a donation} to the Free ! 473: Software Foundation. This will help support development of the rest of the ! 474: GNU system, and other useful software beyond that. Your donation is tax ! 475: deductible. ! 476: ! 477: @node License, Intro, Distrib, Top ! 478: @unnumbered GNU Emacs General Public License ! 479: @center (Clarified 11 Feb 1988) ! 480: ! 481: The license agreements of most software companies keep you at the ! 482: mercy of those companies. By contrast, our general public license is ! 483: intended to give everyone the right to share GNU Emacs. To make ! 484: sure that you get the rights we want you to have, we need to make ! 485: restrictions that forbid anyone to deny you these rights or to ask you ! 486: to surrender the rights. Hence this license agreement. ! 487: ! 488: Specifically, we want to make sure that you have the right to give ! 489: away copies of Emacs, that you receive source code or else can get it ! 490: if you want it, that you can change Emacs or use pieces of it in new ! 491: free programs, and that you know you can do these things. ! 492: ! 493: To make sure that everyone has such rights, we have to forbid you to ! 494: deprive anyone else of these rights. For example, if you distribute ! 495: copies of Emacs, you must give the recipients all the rights that you ! 496: have. You must make sure that they, too, receive or can get the ! 497: source code. And you must tell them their rights. ! 498: ! 499: Also, for our own protection, we must make certain that everyone ! 500: finds out that there is no warranty for GNU Emacs. If Emacs is ! 501: modified by someone else and passed on, we want its recipients to know ! 502: that what they have is not what we distributed, so that any problems ! 503: introduced by others will not reflect on our reputation. ! 504: ! 505: Therefore we (Richard Stallman and the Free Software Foundation, Inc.)@: ! 506: make the following terms which say what you must do to be allowed to ! 507: distribute or change GNU Emacs. ! 508: ! 509: @unnumberedsec Copying Policies ! 510: ! 511: @enumerate ! 512: @item ! 513: You may copy and distribute verbatim copies of GNU Emacs source code as you ! 514: receive it, in any medium, provided that you conspicuously and ! 515: appropriately publish on each file a valid copyright notice ``Copyright ! 516: @copyright{} 1988 Free Software Foundation, Inc.'' (or with whatever year ! 517: is appropriate); keep intact the notices on all files that ! 518: refer to this License Agreement and to the absence of any warranty; and ! 519: give any other recipients of the GNU Emacs program a copy of this License ! 520: Agreement along with the program. You may charge a distribution fee ! 521: for the physical act of transferring a copy. ! 522: ! 523: @item ! 524: You may modify your copy or copies of GNU Emacs source code or ! 525: any portion of it, and copy and distribute such modifications under ! 526: the terms of Paragraph 1 above, provided that you also do the following: ! 527: ! 528: @itemize @bullet ! 529: @item ! 530: cause the modified files to carry prominent notices stating ! 531: who last changed such files and the date of any change; and ! 532: ! 533: @item ! 534: cause the whole of any work that you distribute or publish, that ! 535: in whole or in part contains or is a derivative of GNU Emacs or any ! 536: part thereof, to be licensed at no charge to all third parties on ! 537: terms identical to those contained in this License Agreement ! 538: (except that you may choose to grant more extensive warranty ! 539: protection to some or all third parties, at your option). ! 540: ! 541: @item ! 542: if the modified program serves as a text editor, cause it, when ! 543: started running in the simplest and usual way, to print an ! 544: announcement including a valid copyright notice ``Copyright ! 545: @copyright{} 1988 Free Software Foundation, Inc.'' (or with the ! 546: year that is appropriate), saying that there is no warranty (or ! 547: else, saying that you provide a warranty) and that users may ! 548: redistribute the program under these conditions, and telling the ! 549: user how to view a copy of this License Agreement. ! 550: ! 551: @item ! 552: You may charge a distribution fee for the physical act of ! 553: transferring a copy, and you may at your option offer warranty ! 554: protection in exchange for a fee. ! 555: @end itemize ! 556: ! 557: Mere aggregation of another unrelated program with this program (or its ! 558: derivative) on a volume of a storage or distribution medium does not bring ! 559: the other program under the scope of these terms. ! 560: ! 561: @item ! 562: You may copy and distribute GNU Emacs (or a portion or derivative of it, ! 563: under Paragraph 2) in object code or executable form under the terms ! 564: of Paragraphs 1 and 2 above provided that you also do one of the ! 565: following: ! 566: ! 567: @itemize @bullet ! 568: @item ! 569: accompany it with the complete corresponding machine-readable ! 570: source code, which must be distributed under the terms of ! 571: Paragraphs 1 and 2 above; or, ! 572: ! 573: @item ! 574: accompany it with a written offer, valid for at least three ! 575: years, to give any third party free (except for a nominal ! 576: shipping charge) a complete machine-readable copy of the ! 577: corresponding source code, to be distributed under the terms of ! 578: Paragraphs 1 and 2 above; or, ! 579: ! 580: @item ! 581: accompany it with the information you received as to where the ! 582: corresponding source code may be obtained. (This alternative is ! 583: allowed only for noncommercial distribution and only if you ! 584: received the program in object code or executable form alone.) ! 585: @end itemize ! 586: ! 587: For an executable file, complete source code means all the source code ! 588: for all modules it contains; but, as a special exception, it need not ! 589: include source code for modules which are standard libraries that ! 590: accompany the operating system on which the executable file runs. ! 591: ! 592: @item ! 593: You may not copy, sublicense, distribute or transfer GNU Emacs except ! 594: as expressly provided under this License Agreement. Any attempt ! 595: otherwise to copy, sublicense, distribute or transfer GNU Emacs is ! 596: void and your rights to use GNU Emacs under this License agreement ! 597: shall be automatically terminated. However, parties who have received ! 598: computer software programs from you with this License Agreement will ! 599: not have their licenses terminated so long as such parties remain in ! 600: full compliance. ! 601: ! 602: @item ! 603: If you wish to incorporate parts of GNU Emacs into other free programs ! 604: whose distribution conditions are different, write to the Free Software ! 605: Foundation. We have not yet worked out a simple rule that can be stated ! 606: here, but we will often permit this. We will be guided by the two goals of ! 607: preserving the free status of all derivatives of our free software and of ! 608: promoting the sharing and reuse of software. ! 609: @end enumerate ! 610: ! 611: Your comments and suggestions about our licensing policies and our ! 612: software are welcome! Please contact the Free Software Foundation, Inc., ! 613: 675 Mass Ave, Cambridge, MA 02139. ! 614: ! 615: @iftex ! 616: @vfil ! 617: @eject ! 618: @end iftex ! 619: @unnumberedsec NO WARRANTY ! 620: ! 621: BECAUSE GNU EMACS IS LICENSED FREE OF CHARGE, WE PROVIDE ABSOLUTELY ! 622: NO WARRANTY, TO THE EXTENT PERMITTED BY APPLICABLE STATE LAW. EXCEPT ! 623: WHEN OTHERWISE STATED IN WRITING, FREE SOFTWARE FOUNDATION, INC, ! 624: RICHARD M. STALLMAN AND/OR OTHER PARTIES PROVIDE GNU EMACS ``AS IS'' ! 625: WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, ! 626: BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND ! 627: FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY ! 628: AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE GNU EMACS ! 629: PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY ! 630: SERVICING, REPAIR OR CORRECTION. ! 631: ! 632: IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL FREE SOFTWARE ! 633: FOUNDATION, INC., RICHARD M. STALLMAN, AND/OR ANY OTHER PARTY WHO MAY ! 634: MODIFY AND REDISTRIBUTE GNU EMACS AS PERMITTED ABOVE, BE LIABLE TO YOU ! 635: FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER ! 636: SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR ! 637: INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA ! 638: BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY THIRD PARTIES OR A ! 639: FAILURE OF THE PROGRAM TO OPERATE WITH PROGRAMS NOT DISTRIBUTED BY ! 640: FREE SOFTWARE FOUNDATION, INC.) THE PROGRAM, EVEN IF YOU HAVE BEEN ! 641: ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY ! 642: OTHER PARTY. ! 643: ! 644: @node Intro, Glossary, License, Top ! 645: @unnumbered Introduction ! 646: ! 647: You are reading about GNU Emacs, the GNU incarnation of the advanced, ! 648: self-documenting, customizable, extensible real-time display editor Emacs. ! 649: (The `G' in `GNU' is not silent.) ! 650: ! 651: We say that Emacs is a @dfn{display} editor because normally the text ! 652: being edited is visible on the screen and is updated automatically as you ! 653: type your commands. @xref{Screen,Display}. ! 654: ! 655: We call it a @dfn{real-time} editor because the display is updated very ! 656: frequently, usually after each character or pair of characters you ! 657: type. This minimizes the amount of information you must keep in your ! 658: head as you edit. @xref{Basic,Real-time,Basic Editing}. ! 659: ! 660: We call Emacs advanced because it provides facilities that go beyond ! 661: simple insertion and deletion: filling of text; automatic indentation of ! 662: programs; viewing two or more files at once; and dealing in terms of ! 663: characters, words, lines, sentences, paragraphs, and pages, as well as ! 664: expressions and comments in several different programming languages. It is ! 665: much easier to type one command meaning ``go to the end of the paragraph'' ! 666: than to find that spot with simple cursor keys. ! 667: ! 668: @dfn{Self-documenting} means that at any time you can type a special ! 669: character, @kbd{Control-h}, to find out what your options are. You can ! 670: also use it to find out what any command does, or to find all the commands ! 671: that pertain to a topic. @xref{Help}. ! 672: ! 673: @dfn{Customizable} means that you can change the definitions of Emacs ! 674: commands in little ways. For example, if you use a programming language in ! 675: which comments start with @samp{<**} and end with @samp{**>}, you can tell ! 676: the Emacs comment manipulation commands to use those strings ! 677: (@pxref{Comments}). Another sort of customization is rearrangement of the ! 678: command set. For example, if you prefer the four basic cursor motion ! 679: commands (up, down, left and right) on keys in a diamond pattern on the ! 680: keyboard, you can have it. @xref{Customization}. ! 681: ! 682: @dfn{Extensible} means that you can go beyond simple customization and ! 683: write entirely new commands, programs in the Lisp language to be run by ! 684: Emacs's own Lisp interpreter. Emacs is an ``on-line extensible'' system, ! 685: which means that it is divided into many functions that call each other, ! 686: any of which can be redefined in the middle of an editing session. Any ! 687: part of Emacs can be replaced without making a separate copy of all of ! 688: Emacs. Most of the editing commands of Emacs are written in Lisp already; ! 689: the few exceptions could have been written in Lisp but are written in C for ! 690: efficiency. Although only a programmer can write an extension, anybody can ! 691: use it afterward. ! 692: ! 693: @node Screen, Characters, Concept Index, Top ! 694: ! 695: @chapter The Organization of the Screen ! 696: @cindex screen ! 697: ! 698: Emacs divides the screen into several areas, each of which contains ! 699: its own sorts of information. The biggest area, of course, is the one ! 700: in which you usually see the text you are editing. ! 701: ! 702: When you are using Emacs, the screen is divided into a number of ! 703: @dfn{windows}. Initially there is one text window occupying all but the ! 704: last line, plus the special @dfn{echo area} or @dfn{minibuffer window} in ! 705: the last line. The text window can be subdivided horizontally or ! 706: vertically into multiple text windows, each of which can be used for a ! 707: different file (@pxref{Windows}). The window that the cursor is in is the ! 708: @dfn{selected window}, in which editing takes place. The other windows are ! 709: just for reference unless you select one of them. ! 710: ! 711: Each text window's last line is a @dfn{mode line} which describes what is ! 712: going on in that window. It is in inverse video if the terminal supports ! 713: that, and contains text that starts like @samp{-----Emacs:@: @var{something}}. Its ! 714: purpose is to indicate what buffer is being displayed above it in the ! 715: window; what major and minor modes are in use; and whether the buffer's ! 716: text has been changed. ! 717: ! 718: @menu ! 719: * Point:: The place in the text where editing commands operate. ! 720: * Echo Area:: Short messages appear at the bottom of the screen. ! 721: * Mode Line:: Interpreting the mode line. ! 722: @end menu ! 723: ! 724: @node Point, Echo Area, Screen, Screen ! 725: @section Point ! 726: @cindex point ! 727: @cindex cursor ! 728: ! 729: When Emacs is running, the terminal's cursor shows the location at ! 730: which editing commands will take effect. This location is called ! 731: @dfn{point}. Other commands move point through the text, so that you ! 732: can edit at different places in it. ! 733: ! 734: While the cursor appears to point @var{at} a character, point should be ! 735: thought of as @var{between} two characters; it points @var{before} the character ! 736: that the cursor appears on top of. Sometimes people speak of ``the ! 737: cursor'' when they mean ``point'', or speak of commands that move point as ! 738: ``cursor motion'' commands. ! 739: ! 740: Terminals have only one cursor, and when output is in progress it must ! 741: appear where the typing is being done. This does not mean that point is ! 742: moving. It is only that Emacs has no way to show you the location of point ! 743: except when the terminal is idle. ! 744: ! 745: If you are editing several files in Emacs, each file has its own point ! 746: location. A file that is not being displayed remembers where point is so ! 747: that it can be seen when you look at that file again. ! 748: ! 749: When there are multiple text windows, each window has its own point ! 750: location. The cursor shows the location of point in the selected window. ! 751: This also is how you can tell which window is selected. If the same buffer ! 752: appears in more than one window, point can be moved in each window ! 753: independently. ! 754: ! 755: The term `point' comes from the character @samp{.}, which was the ! 756: command in TECO (the language in which the original Emacs was written) ! 757: for accessing the value now called `point'. ! 758: ! 759: @node Echo Area, Mode Line, Point, Screen ! 760: @section The Echo Area ! 761: @cindex echo area ! 762: ! 763: The line at the bottom of the screen (below the mode line) is the ! 764: @dfn{echo area}. It is used to display small amounts of text for several ! 765: purposes. ! 766: ! 767: @dfn{Echoing} means printing out the characters that you type. Emacs ! 768: never echoes single-character commands, and multi-character commands are ! 769: echoed only if you pause while typing them. As soon as you pause for more ! 770: than a second in the middle of a command, all the characters of the command ! 771: so far are echoed. This is intended to @dfn{prompt} you for the rest of ! 772: the command. Once echoing has started, the rest of the command is echoed ! 773: immediately when you type it. This behavior is designed to give confident ! 774: users fast response, while giving hesitant users maximum feedback. You ! 775: can change this behavior by setting a variable (@pxref{Display Vars}). ! 776: ! 777: If a command cannot be executed, it may print an @dfn{error message} in ! 778: the echo area. Error messages are accompanied by a beep or by flashing the ! 779: screen. Also, any input you have typed ahead is thrown away when an error ! 780: happens. ! 781: ! 782: Some commands print informative messages in the echo area. These ! 783: messages look much like error messages, but they are not announced with a ! 784: beep and do not throw away input. Sometimes the message tells you what the ! 785: command has done, when this is not obvious from looking at the text being ! 786: edited. Sometimes the sole purpose of a command is to print a message ! 787: giving you specific information. For example, the command @kbd{C-x =} is ! 788: used to print a message describing the character position of point in the ! 789: text and its current column in the window. Commands that take a long time ! 790: often display messages ending in @samp{...} while they are working, and ! 791: add @samp{done} at the end when they are finished. ! 792: ! 793: The echo area is also used to display the @dfn{minibuffer}, a window that ! 794: is used for reading arguments to commands, such as the name of a file to be ! 795: edited. When the minibuffer is in use, the echo area begins with a prompt ! 796: string that usually ends with a colon; also, the cursor appears in that line ! 797: because it is the selected window. You can always get out of the ! 798: minibuffer by typing @kbd{C-g}. @xref{Minibuffer}. ! 799: ! 800: @node Mode Line,, Echo Area, Screen ! 801: @section The Mode Line ! 802: @cindex mode line ! 803: @cindex top level ! 804: ! 805: Each text window's last line is a @dfn{mode line} which describes what is ! 806: going on in that window. When there is only one text window, the mode line ! 807: appears right above the echo area. The mode line is in inverse video if ! 808: the terminal supports that, starts and ends with dashes, and contains text ! 809: like @samp{Emacs:@: @var{something}}. ! 810: ! 811: If a mode line has something else in place of @samp{Emacs:@: @var{something}}, ! 812: then the window above it is in a special subsystem such as Dired. The mode ! 813: line then indicates the status of the subsystem. ! 814: ! 815: Normally, the mode line has the following appearance: ! 816: ! 817: @example ! 818: --@var{ch}-Emacs: @var{buf} (@var{major} @var{minor})----@var{pos}------ ! 819: @end example ! 820: ! 821: @noindent ! 822: This gives information about the buffer being displayed in the window: the ! 823: buffer's name, what major and minor modes are in use, whether the buffer's ! 824: text has been changed, and how far down the buffer you are currently ! 825: looking. ! 826: ! 827: @var{ch} contains two stars @samp{**} if the text in the buffer has been ! 828: edited (the buffer is ``modified''), or @samp{--} if the buffer has not been ! 829: edited. Exception: for a read-only buffer, it is @samp{%%}. ! 830: ! 831: @var{buf} is the name of the window's chosen @dfn{buffer}. The chosen buffer ! 832: in the selected window (the window that the cursor is in) is also Emacs's ! 833: selected buffer, the one that editing takes place in. When we speak of ! 834: what some command does to ``the buffer'', we are talking about the ! 835: currently selected buffer. @xref{Buffers}. ! 836: ! 837: @var{pos} tells you whether there is additional text above the top of the ! 838: screen, or below the bottom. If your file is small and it is all on the ! 839: screen, @var{pos} is @samp{All}. Otherwise, it is @samp{Top} if you are ! 840: looking at the beginning of the file, @samp{Bot} if you are looking at the ! 841: end of the file, or @samp{@var{nn}%}, where @var{nn} is the percentage of ! 842: the file above the top of the screen.@refill ! 843: ! 844: @var{major} is the name of the @dfn{major mode} in effect in the buffer. At ! 845: any time, each buffer is in one and only one of the possible major modes. ! 846: The major modes available include Fundamental mode (the least specialized), ! 847: Text mode, Lisp mode, and C mode. @xref{Major Modes}, for details ! 848: of how the modes differ and how to select one.@refill ! 849: ! 850: @var{minor} is a list of some of the @dfn{minor modes} that are turned on ! 851: at the moment in the window's chosen buffer. @samp{Fill} means that Auto ! 852: Fill mode is on. @samp{Abbrev} means that Word Abbrev mode is on. ! 853: @samp{Ovwrt} means that Overwrite mode is on. @xref{Minor Modes}, for more ! 854: information. @samp{Narrow} means that the buffer being displayed has ! 855: editing restricted to only a portion of its text. This is not really a ! 856: minor mode, but is like one. @xref{Narrowing}. @samp{Def} means that a ! 857: keyboard macro is being defined. @xref{Keyboard Macros}. ! 858: ! 859: Some buffers display additional information after the minor modes. For ! 860: example, Rmail buffers display the current message number and the total ! 861: number of messages. Compilation buffers and Shell mode display the status ! 862: of the subprocess. ! 863: ! 864: In addition, if Emacs is currently inside a recursive editing level, ! 865: square brackets (@samp{[@dots{}]}) appear around the parentheses that ! 866: surround the modes. If Emacs is in one recursive editing level within ! 867: another, double square brackets appear, and so on. Since this information ! 868: pertains to Emacs in general and not to any one buffer, the square brackets ! 869: appear in every mode line on the screen or not in any of them. ! 870: @xref{Recursive Edit}.@refill ! 871: ! 872: @findex display-time ! 873: Emacs can optionally display the time and system load in all mode lines. ! 874: To enable this feature, type @kbd{M-x display-time}. The information added ! 875: to the mode line usually appears after the file name, before the mode names ! 876: and their parentheses. It looks like this: ! 877: ! 878: @example ! 879: @var{hh}:@var{mm}pm @var{l.ll} [@var{d}] ! 880: @end example ! 881: ! 882: @noindent ! 883: (Some fields may be missing if your operating system cannot support them.) ! 884: @var{hh} and @var{mm} are the hour and minute, followed always by @samp{am} ! 885: or @samp{pm}. @var{l.ll} is the average number of running processes in the ! 886: whole system recently. @var{d} is an approximate index of the ratio of ! 887: disk activity to cpu activity for all users. ! 888: ! 889: The word @samp{Mail} appears after the load level if there is mail for ! 890: you that you have not read yet. ! 891: ! 892: @vindex mode-line-inverse-video ! 893: Customization note: the variable @code{mode-line-inverse-video} controls ! 894: whether the mode line is displayed in inverse video (assuming the terminal ! 895: supports it); @code{nil} means no inverse video. The default is @code{t}. ! 896: ! 897: @iftex ! 898: @chapter Characters, Keys and Commands ! 899: ! 900: This chapter explains the character set used by Emacs for input commands ! 901: and for the contents of files, and also explains the concepts of ! 902: @dfn{keys} and @dfn{commands} which are necessary for understanding how ! 903: your keyboard input is understood by Emacs. ! 904: @end iftex ! 905: ! 906: @node Characters, Keys, Screen, Top ! 907: @section The Emacs Character Set ! 908: @cindex character set ! 909: @cindex ASCII ! 910: ! 911: GNU Emacs uses the ASCII character set, which defines 128 different ! 912: character codes. Some of these codes are assigned graphic symbols such ! 913: as @samp{a} and @samp{=}; the rest are control characters, such as ! 914: @kbd{Control-a} (also called @kbd{C-a} for short). @kbd{C-a} gets its name ! 915: from the fact that you type it by holding down the @key{CTRL} key and ! 916: then pressing @kbd{a}. There is no distinction between @kbd{C-a} and ! 917: @kbd{C-A}; they are the same character.@refill ! 918: ! 919: Some control characters have special names, and special keys you can ! 920: type them with: @key{RET}, @key{TAB}, @key{LFD}, @key{DEL} and @key{ESC}. ! 921: The space character is usually referred to below as @key{SPC}, even though ! 922: strictly speaking it is a graphic character whose graphic happens to be ! 923: blank.@refill ! 924: ! 925: Emacs extends the 7-bit ASCII code to an 8-bit code by adding an extra ! 926: bit to each character. This makes 256 possible command characters. The ! 927: additional bit is called Meta. Any ASCII character can be made Meta; ! 928: examples of Meta characters include @kbd{Meta-a} (@kbd{M-a}, for short), ! 929: @kbd{M-A} (not the same character as @kbd{M-a}, but those two characters ! 930: normally have the same meaning in Emacs), @kbd{M-@key{RET}}, and ! 931: @kbd{M-C-a}. For traditional reasons, @kbd{M-C-a} is usually called ! 932: @kbd{C-M-a}; logically speaking, the order in which the modifier keys ! 933: @key{CTRL} and @key{META} are mentioned does not matter.@refill ! 934: ! 935: @cindex Control ! 936: @cindex Meta ! 937: @cindex C- ! 938: @cindex M- ! 939: @cindex ESC replacing META key ! 940: Some terminals have a @key{META} key, and allow you to type Meta ! 941: characters by holding this key down. Thus, @kbd{Meta-a} is typed by ! 942: holding down @key{META} and pressing @kbd{a}. The @key{META} key works ! 943: much like the @key{SHIFT} key. Such a key is not always labeled ! 944: @key{META}, however, as this function is often a special option for a key ! 945: with some other primary purpose.@refill ! 946: ! 947: If there is no @key{META} key, you ! 948: can still type Meta characters using two-character sequences starting with ! 949: @key{ESC}. Thus, to enter @kbd{M-a}, you could type @kbd{@key{ESC} a}. To ! 950: enter @kbd{C-M-a}, you would type @kbd{@key{ESC} C-a}. @key{ESC} is ! 951: allowed on terminals with Meta keys, too, in case you have formed a habit ! 952: of using it.@refill ! 953: ! 954: @vindex meta-flag ! 955: Emacs believes the terminal has a @key{META} key if the variable ! 956: @code{meta-flag} is non-@code{nil}. Normally this is set automatically ! 957: according to the termcap entry for your terminal type. However, sometimes ! 958: the termcap entry is wrong, and then it is useful to set this variable ! 959: yourself. @xref{Variables}, for how to do this. ! 960: ! 961: Emacs buffers also use an 8-bit character set, because bytes have 8 bits, ! 962: but only the ASCII characters are considered meaningful. ASCII graphic ! 963: characters in Emacs buffers are displayed with their graphics. @key{LFD} ! 964: is the same as a newline character; it is displayed by starting a new line. ! 965: @key{TAB} is displayed by moving to the next tab stop column (usually every ! 966: 8 columns). Other control characters are displayed as a caret (@samp{^}) ! 967: followed by the non-control version of the character; thus, @kbd{C-a} is ! 968: displayed as @samp{^A}. Non-ASCII characters 128 and up are displayed with ! 969: octal escape sequences; thus, character code 243 (octal), also called ! 970: @kbd{M-#} when used as an input character, is displayed as @samp{\243}. ! 971: ! 972: @node Keys, Commands, Characters, Top ! 973: @section Keys ! 974: ! 975: @cindex key ! 976: @cindex prefix key ! 977: A @dfn{complete key}---where `key' is short for @dfn{key sequence}---is a ! 978: sequence of keystrokes that are understood by Emacs as a unit, as a single ! 979: command (possibly undefined). Most single characters constitute complete ! 980: keys in the standard Emacs command set; there are also some multi-character ! 981: keys. Examples of complete keys are @kbd{C-a}, @kbd{X}, @key{RET}, ! 982: @kbd{C-x C-f} and @kbd{C-x 4 C-f}.@refill ! 983: ! 984: @kindex C-c ! 985: @kindex C-x ! 986: @kindex C-h ! 987: @kindex ESC ! 988: A @dfn{prefix key} is a sequence of keystrokes that are the beginning of ! 989: a complete key, but not a whole one. Prefix keys and complete keys are ! 990: collectively called @dfn{keys}. ! 991: ! 992: A prefix key is the beginning of a series of longer sequences that are ! 993: valid keys; adding any single character to the end of the prefix gives a ! 994: valid key, which could be defined as an Emacs command, or could be a prefix ! 995: itself. For example, @kbd{C-x} is standardly defined as a prefix, so ! 996: @kbd{C-x} and the next input character combine to make a two-character key. ! 997: There are 256 different two-character keys starting with @kbd{C-x}, one for ! 998: each possible second character. Many of these two-character keys starting ! 999: with @kbd{C-x} are standardly defined as Emacs commands. Notable examples ! 1000: include @kbd{C-x C-f} and @kbd{C-x s} (@pxref{Files}). ! 1001: ! 1002: Adding one character to a prefix key does not have to form a complete ! 1003: key. It could make another, longer prefix. For example, @kbd{C-x 4} is ! 1004: itself a prefix that leads to 256 different three-character keys, including ! 1005: @kbd{C-x 4 f}, @kbd{C-x 4 b} and so on. It would be possible to define one ! 1006: of those three-character sequences as a prefix, creating a series of ! 1007: four-character keys, but we did not define any of them this way.@refill ! 1008: ! 1009: By contrast, the two-character sequence @kbd{C-f C-k} is not a key, ! 1010: because the @kbd{C-f} is a complete key in itself. It's impossible to give ! 1011: @kbd{C-f C-k} an independent meaning as a command as long as @kbd{C-f} ! 1012: retains its meaning. @kbd{C-f C-k} is two commands.@refill ! 1013: ! 1014: All told, the prefix keys in Emacs are @kbd{C-c}, @kbd{C-x}, @kbd{C-h}, ! 1015: @kbd{C-x 4}, and @key{ESC}. But this is not built in; it is just a matter ! 1016: of Emacs's standard key bindings. In customizing Emacs, you could make ! 1017: new prefix keys, or eliminate these. @xref{Key Bindings}.@refill ! 1018: ! 1019: Whether a sequence is a key can be changed by customization. For ! 1020: example, if you redefine @kbd{C-f} as a prefix, @kbd{C-f C-k} automatically ! 1021: becomes a key (complete, unless you define it too as a prefix). ! 1022: Conversely, if you remove the prefix definition of @kbd{C-x 4}, then ! 1023: @kbd{C-x 4 f} (or @kbd{C-x 4 @var{anything}}) is no longer a key. ! 1024: ! 1025: @node Commands, Entering Emacs, Keys, Top ! 1026: @section Keys and Commands ! 1027: ! 1028: @cindex binding ! 1029: @cindex customization ! 1030: @cindex keymap ! 1031: @cindex function ! 1032: @cindex command ! 1033: This manual is full of passages that tell you what particular keys do. ! 1034: But Emacs does not assign meanings to keys directly. Instead, Emacs ! 1035: assigns meanings to @dfn{functions}, and then gives keys their meanings by ! 1036: @dfn{binding} them to functions. ! 1037: ! 1038: A function is a Lisp object that can be executed as a program. Usually ! 1039: it is a Lisp symbol which has been given a function definition; every ! 1040: symbol has a name, usually made of a few English words separated by dashes, ! 1041: such as @code{next-line} or @code{forward-word}. It also has a ! 1042: @dfn{definition} which is a Lisp program; this is what makes the function ! 1043: do what it does. Only some functions can be the bindings of keys; these ! 1044: are functions whose definitions use @code{interactive} to specify how to ! 1045: call them interactively. Such functions are called @dfn{commands}, and ! 1046: their names are @dfn{command names}. More information on this subject will ! 1047: appear in the @i{GNU Emacs Lisp Manual} (which is not yet written). ! 1048: ! 1049: The bindings between keys and functions are recorded in various tables ! 1050: called @dfn{keymaps}. @xref{Keymaps}. ! 1051: ! 1052: When we say that ``@kbd{C-n} moves down vertically one line'' we are ! 1053: glossing over a distinction that is irrelevant in ordinary use but is vital ! 1054: in understanding how to customize Emacs. It is the function ! 1055: @code{next-line} that is programmed to move down vertically. @kbd{C-n} has ! 1056: this effect @i{because} it is bound to that function. If you rebind ! 1057: @kbd{C-n} to the function @code{forward-word} then @kbd{C-n} will move ! 1058: forward by words instead. Rebinding keys is a common method of ! 1059: customization.@refill ! 1060: ! 1061: In the rest of this manual, we usually ignore this subtlety to keep ! 1062: things simple. To give the customizer the information he needs, we ! 1063: state the name of the command which really does the work in parentheses ! 1064: after mentioning the key that runs it. For example, we will say that ! 1065: ``The command @kbd{C-n} (@code{next-line}) moves point vertically down,'' ! 1066: meaning that @code{next-line} is a command that moves vertically down ! 1067: and @kbd{C-n} is a key that is standardly bound to it. ! 1068: ! 1069: @cindex variables ! 1070: While we are on the subject of information for customization only, it's a ! 1071: good time to tell you about @dfn{variables}. Often the description of a ! 1072: command will say, ``To change this, set the variable @code{mumble-foo}.'' ! 1073: A variable is a name used to remember a value. Most of the variables ! 1074: documented in this manual exist just to facilitate customization: some ! 1075: command or other part of Emacs examines the variable and behaves ! 1076: differently accordingly. Until you are interested in customizing, you can ! 1077: ignore the information about variables. When you are ready to be ! 1078: interested, read the basic information on variables, and then the ! 1079: information on individual variables will make sense. @xref{Variables}. ! 1080: ! 1081: @node Entering Emacs, Exiting, Commands, Top ! 1082: @chapter Entering and Exiting Emacs ! 1083: @cindex entering Emacs ! 1084: ! 1085: The usual way to invoke Emacs is just to type @kbd{emacs @key{RET}} at ! 1086: the shell. Emacs clears the screen and then displays an initial advisor ! 1087: message and copyright notice. You can begin typing Emacs commands ! 1088: immediately afterward. ! 1089: ! 1090: Some operating systems insist on discarding all type-ahead when Emacs ! 1091: starts up; they give Emacs no way to prevent this. Therefore, it is ! 1092: wise to wait until Emacs clears the screen before typing your first ! 1093: editing command. ! 1094: ! 1095: @vindex initial-major-mode ! 1096: Before Emacs reads the first command, you have not had a chance to give a ! 1097: command to specify a file to edit. But Emacs must always have a current ! 1098: buffer for editing. In an attempt to do something useful, Emacs presents a ! 1099: buffer named @samp{*scratch*} which is in Lisp Interaction mode; you can ! 1100: use it to type Lisp expressions and evaluate them, or you can ignore that ! 1101: capability and simply doodle. (You can specify a different major mode for ! 1102: this buffer by setting the variable @code{initial-major-mode} in your init ! 1103: file. @xref{Init File}.) ! 1104: ! 1105: It is also possible to specify files to be visited, Lisp files to be ! 1106: loaded, and functions to be called, by giving Emacs arguments in the ! 1107: shell command line. @xref{Command Switches}. ! 1108: ! 1109: @node Exiting, Command Switches, Entering Emacs, Top ! 1110: @section Exiting Emacs ! 1111: @cindex exiting ! 1112: @cindex killing Emacs ! 1113: @cindex suspending ! 1114: ! 1115: There are two commands for exiting Emacs because there are two kinds of ! 1116: exiting: @dfn{suspending} Emacs and @dfn{killing} Emacs. @dfn{Suspending} means ! 1117: stopping Emacs temporarily and returning control to its superior (usually ! 1118: the shell), allowing you to resume editing later in the same Emacs job, ! 1119: with the same files, same kill ring, same undo history, and so on. This is ! 1120: the usual way to exit. @dfn{Killing} Emacs means destroying the Emacs job. ! 1121: You can run Emacs again later, but you will get a fresh Emacs; there is no ! 1122: way to resume the same editing session after it has been killed. ! 1123: ! 1124: @table @kbd ! 1125: @item C-z ! 1126: Suspend Emacs (@code{suspend-emacs}). ! 1127: @item C-x C-c ! 1128: Kill Emacs (@code{save-buffers-kill-emacs}). ! 1129: @end table ! 1130: ! 1131: @kindex C-z ! 1132: @findex suspend-emacs ! 1133: To suspend Emacs, type @kbd{C-z} (@code{suspend-emacs}). This takes ! 1134: you back to the shell from which you invoked Emacs. You can resume ! 1135: Emacs with the command @code{%emacs} if you are using the C shell. ! 1136: ! 1137: On systems that do not permit programs to be suspended, @kbd{C-z} runs an ! 1138: inferior shell that communicates directly with the terminal, and Emacs ! 1139: waits until you exit the subshell. The only way on these systems to get ! 1140: back to the shell from which Emacs was run (to log out, for example) is to ! 1141: kill Emacs. @kbd{C-d} or @code{exit} are typical commands to exit a ! 1142: subshell. ! 1143: ! 1144: @kindex C-x C-c ! 1145: @findex save-buffers-kill-emacs ! 1146: To kill Emacs, type @kbd{C-x C-c} (@code{save-buffers-kill-emacs}). A ! 1147: two-character key is used for this to make it harder to type. Unless a ! 1148: numeric argument is used, this command first offers to save any modified ! 1149: buffers. If you do not save them all, it asks for reconfirmation with ! 1150: @kbd{yes} before killing Emacs, since any changes not saved before that will be ! 1151: lost forever. Also, if any subprocesses are still running, @kbd{C-x C-c} ! 1152: asks for confirmation about them, since killing Emacs will kill the ! 1153: subprocesses immediately. ! 1154: ! 1155: In most programs running on Unix, certain characters may instantly ! 1156: suspend or kill the program. (In Berkeley Unix these characters are ! 1157: normally @kbd{C-z} and @kbd{C-c}.) @b{This Unix feature is turned off ! 1158: while you are in Emacs.} The meanings of @kbd{C-z} and @kbd{C-x C-c} as ! 1159: keys in Emacs were inspired by the standard Berkeley Unix meanings of ! 1160: @kbd{C-z} and @kbd{C-c}, but that is their only relationship with ! 1161: Unix. You could customize these keys to do anything (@pxref{Keymaps}). ! 1162: ! 1163: @c ??? What about system V here? ! 1164: ! 1165: @node Command Switches, Basic, Exiting, Top ! 1166: @section Command Line Switches and Arguments ! 1167: @cindex command line arguments ! 1168: @cindex arguments (from shell) ! 1169: ! 1170: ! 1171: GNU Emacs supports command line arguments to request various actions ! 1172: when invoking Emacs. These are for compatibility with other editors and ! 1173: for sophisticated activities. They are not needed for ordinary editing ! 1174: with Emacs, so new users can skip this section. ! 1175: ! 1176: You may be used to using command line arguments with other editors ! 1177: to specify which file to edit. That's because many other editors are ! 1178: designed to be started afresh each time you want to edit. You ! 1179: edit one file and then exit the editor. The next time you want to edit ! 1180: either another file or the same one, you must run the editor again. ! 1181: With these editors, it makes sense to use a command line argument ! 1182: to say which file to edit. ! 1183: ! 1184: The recommended way to use GNU Emacs is to start it only once, just after ! 1185: you log in, and do all your editing in the same Emacs process. Each time ! 1186: you want to edit a different file, you visit it with the existing Emacs, ! 1187: which eventually comes to have many files in it ready for editing. Usually ! 1188: you do not kill the Emacs until you are about to log out. ! 1189: ! 1190: When files are nearly always read by typing commands to an editor that is ! 1191: already running, command line arguments for specifying a file when the ! 1192: editor is started are seldom needed. ! 1193: ! 1194: Emacs accepts command-line arguments that specify files to visit, ! 1195: functions to call, and other activities and operating modes. ! 1196: ! 1197: The command arguments are processed in the order they appear in the ! 1198: command argument list; however, certain arguments (the ones in the second ! 1199: table) must be at the front of the list if they are used. ! 1200: ! 1201: Here are the arguments allowed: ! 1202: ! 1203: @table @samp ! 1204: @item @var{file} ! 1205: Visit @var{file} using @code{find-file}. @xref{Visiting}. ! 1206: ! 1207: @item +@var{linenum} @var{file} ! 1208: Visit @var{file} using @code{find-file}, then go to line number ! 1209: @var{linenum} in it. ! 1210: ! 1211: @item -l @var{file} ! 1212: @itemx -load @var{file} ! 1213: Load a file @var{file} of Lisp code with the function @code{load}. ! 1214: @xref{Lisp Libraries}. ! 1215: ! 1216: @item -f @var{function} ! 1217: @itemx -funcall @var{function} ! 1218: Call Lisp function @var{function} with no arguments. ! 1219: ! 1220: @item -i @var{file} ! 1221: @itemx -insert @var{file} ! 1222: Insert the contents of @var{file} into the current buffer. ! 1223: This is like what @kbd{M-x insert-buffer} does; @xref{Misc File Ops}. ! 1224: ! 1225: @item -kill ! 1226: Exit from Emacs without asking for confirmation. ! 1227: @end table ! 1228: ! 1229: The remaining switches are recognized only at the beginning of the ! 1230: command line. If more than one of them appears, they must appear in the ! 1231: order that they appear in this table. ! 1232: ! 1233: @table @samp ! 1234: @item -t @var{device} ! 1235: Use @var{device} as the device for terminal input and output. ! 1236: ! 1237: @item -d @var{display} ! 1238: When running with the X window system, use the display named @var{display} ! 1239: to make the window that serves as Emacs's terminal. ! 1240: ! 1241: @cindex batch mode ! 1242: @item -batch ! 1243: Run Emacs in @dfn{batch mode}, which means that the text being edited is ! 1244: not displayed and the standard Unix interrupt characters such as @kbd{C-z} ! 1245: and @kbd{C-c} continue to have their normal effect. Emacs in batch mode ! 1246: outputs to @code{stdout} only what would normally be printed in the echo ! 1247: area under program control. ! 1248: ! 1249: Batch mode is used for running programs written in Emacs Lisp from ! 1250: shell scripts, makefiles, and so on. Normally the @samp{-l} switch ! 1251: or @samp{-f} switch will be used as well, to invoke a Lisp program ! 1252: to do the batch processing. ! 1253: ! 1254: @samp{-batch} implies @samp{-q} (do not load an init file). It also causes ! 1255: Emacs to kill itself after all command switches have been processed. In ! 1256: addition, auto-saving is not done except in buffers for which it has been ! 1257: explicitly requested. ! 1258: ! 1259: @item -q ! 1260: @itemx -no-init-file ! 1261: Do not load your Emacs init file @file{~/.emacs}. ! 1262: ! 1263: @item -u @var{user} ! 1264: @itemx -user @var{user} ! 1265: Load @var{user}'s Emacs init file @file{~@var{user}/.emacs} instead of ! 1266: your own. ! 1267: @end table ! 1268: ! 1269: @vindex command-line-args ! 1270: Note that the init file can get access to the command line argument ! 1271: values as the elements of a list in the variable @code{command-line-args}. ! 1272: (The arguments in the second table above will already have been processed ! 1273: and will not be in the list.) The init file can override the normal ! 1274: processing of the other arguments by setting this variable. ! 1275: ! 1276: One way to use command switches is to visit many files automatically: ! 1277: ! 1278: @example ! 1279: emacs *.c ! 1280: @end example ! 1281: ! 1282: @noindent ! 1283: passes each @code{.c} file as a separate argument to Emacs, so that Emacs ! 1284: visits each file (@pxref{Visiting}). ! 1285: ! 1286: Here is an advanced example that assumes you have a Lisp program ! 1287: file called @file{hack-c-program.el} which, when loaded, performs some ! 1288: useful operation on current buffer, expected to be a C program. ! 1289: ! 1290: @example ! 1291: emacs -batch foo.c -l hack-c-program -f save-buffer -kill > log ! 1292: @end example ! 1293: ! 1294: @noindent ! 1295: Here Emacs is told to visit @file{foo.c}, load @file{hack-c-program.el} ! 1296: (which makes changes in the visited file), save @file{foo.c} (note that ! 1297: @code{save-buffer} is the function that @kbd{C-x C-s} is bound to), and ! 1298: then exit to the shell that this command was done with. @samp{-batch} ! 1299: guarantees there will be no problem redirecting output to @file{log}, ! 1300: because Emacs will not assume that it has a display terminal to work with. ! 1301: ! 1302: @node Basic, Undo, Command Switches, Top ! 1303: @chapter Basic Editing Commands ! 1304: ! 1305: @kindex C-h t ! 1306: @findex help-with-tutorial ! 1307: We now give the basics of how to enter text, make corrections, and ! 1308: save the text in a file. If this material is new to you, you might ! 1309: learn it more easily by running the Emacs learn-by-doing tutorial. To ! 1310: do this, type @kbd{Control-h t} (@code{help-with-tutorial}). ! 1311: ! 1312: @section Inserting Text ! 1313: ! 1314: @cindex insertion ! 1315: @cindex point ! 1316: @cindex cursor ! 1317: @cindex graphic characters ! 1318: To insert printing characters into the text you are editing, just type ! 1319: them. This inserts the character into the buffer at the cursor (that is, ! 1320: at @dfn{point}; @pxref{Point}). The cursor moves forward. Any characters ! 1321: after the cursor move forward too. If the text in the buffer is ! 1322: @samp{FOOBAR}, with the cursor before the @samp{B}, then if you type ! 1323: @kbd{XX}, you get @samp{FOOXXBAR}, with the cursor still before the ! 1324: @samp{B}. ! 1325: ! 1326: @kindex DEL ! 1327: @cindex deletion ! 1328: To @dfn{delete} text you have just inserted, use @key{DEL}. @key{DEL} ! 1329: deletes the character @var{before} the cursor (not the one that the cursor ! 1330: is on top of or under; that is the character @var{after} the cursor). The ! 1331: cursor and all characters after it move backwards. Therefore, if you type ! 1332: a printing character and then type @key{DEL}, they cancel out. ! 1333: ! 1334: @kindex RET ! 1335: @cindex newline ! 1336: To end a line and start typing a new one, type @key{RET}. This inserts ! 1337: a newline character in the buffer. If point is in the middle of a line, ! 1338: @key{RET} splits the line. Typing @key{DEL} when the cursor is at the ! 1339: beginning of a line rubs out the newline before the line, thus joining the ! 1340: line with the preceding line. ! 1341: ! 1342: Emacs will split lines automatically when they become too long, if you ! 1343: turn on a special mode called @dfn{Auto Fill} mode. @xref{Filling}, for ! 1344: how to use Auto Fill mode. ! 1345: ! 1346: @findex delete-backward-char ! 1347: @findex newline ! 1348: @findex self-insert ! 1349: Customization information: @key{DEL} in most modes runs the command named ! 1350: @code{delete-backward-char}; @key{RET} runs the command @code{newline}, and ! 1351: self-inserting printing characters run the command @code{self-insert}, ! 1352: which inserts whatever character was typed to invoke it. Some major modes ! 1353: rebind @key{DEL} to other commands. ! 1354: ! 1355: @cindex quoting ! 1356: @kindex C-q ! 1357: @findex quoted-insert ! 1358: Direct insertion works for printing characters and @key{SPC}, but other ! 1359: characters act as editing commands and do not insert themselves. If you ! 1360: need to insert a control character or a character whose code is above 200 ! 1361: octal, you must @dfn{quote} it by typing the character @kbd{control-q} ! 1362: (@code{quoted-insert}) first. There are two ways to use @kbd{C-q}:@refill ! 1363: ! 1364: @itemize @bullet ! 1365: @item ! 1366: @kbd{Control-q} followed by any non-graphic character (even @kbd{C-g}) ! 1367: inserts that character. ! 1368: @item ! 1369: @kbd{Control-q} followed by three octal digits inserts the character ! 1370: with the specified character code. ! 1371: @end itemize ! 1372: ! 1373: @noindent ! 1374: A numeric argument to @kbd{C-q} specifies how many copies of the ! 1375: quoted character should be inserted (@pxref{Arguments}). ! 1376: ! 1377: If you prefer to have text characters replace (overwrite) existing ! 1378: text rather than shove it to the right, you can enable Overwrite mode, ! 1379: a minor mode. @xref{Minor Modes}. ! 1380: ! 1381: @section Changing the Location of Point ! 1382: ! 1383: To do more than insert characters, you have to know how to move ! 1384: point (@pxref{Point}). Here are a few of the commands for doing that. ! 1385: ! 1386: @kindex C-a ! 1387: @kindex C-e ! 1388: @kindex C-f ! 1389: @kindex C-b ! 1390: @kindex C-n ! 1391: @kindex C-p ! 1392: @kindex C-l ! 1393: @kindex C-t ! 1394: @kindex M-> ! 1395: @kindex M-< ! 1396: @kindex M-r ! 1397: @findex beginning-of-line ! 1398: @findex end-of-line ! 1399: @findex forward-char ! 1400: @findex backward-char ! 1401: @findex next-line ! 1402: @findex previous-line ! 1403: @findex recenter ! 1404: @findex transpose-chars ! 1405: @findex beginning-of-buffer ! 1406: @findex end-of-buffer ! 1407: @findex goto-char ! 1408: @findex goto-line ! 1409: @findex move-to-window-line ! 1410: @table @kbd ! 1411: @item C-a ! 1412: Move to the beginning of the line (@code{beginning-of-line}). ! 1413: @item C-e ! 1414: Move to the end of the line (@code{end-of-line}). ! 1415: @item C-f ! 1416: Move forward one character (@code{forward-char}). ! 1417: @item C-b ! 1418: Move backward one character (@code{backward-char}). ! 1419: @item M-f ! 1420: Move forward one word (@code{forward-word}). ! 1421: @item M-b ! 1422: Move backward one word (@code{backward-word}). ! 1423: @item C-n ! 1424: Move down one line, vertically (@code{next-line}). This command ! 1425: attempts to keep the horizontal position unchanged, so if you start in ! 1426: the middle of one line, you end in the middle of the next. When on ! 1427: the last line of text, @kbd{C-n} creates a new line and moves onto it. ! 1428: @item C-p ! 1429: Move up one line, vertically (@code{previous-line}). ! 1430: @item C-l ! 1431: Clear the screen and reprint everything (@code{recenter}). Text moves ! 1432: on the screen to bring point to the center of the window. ! 1433: @item M-r ! 1434: Move point to left margin on the line halfway down the screen or ! 1435: window (@code{move-to-window-line}). Text does not move on the ! 1436: screen. A numeric argument says how many screen lines down from the ! 1437: top of the window (zero for the top). A negative argument counts from ! 1438: the bottom (@minus{}1 for the bottom). ! 1439: @item C-t ! 1440: Transpose two characters, the ones before and after the cursor ! 1441: (@code{transpose-chars}). ! 1442: @item M-< ! 1443: Move to the top of the buffer (@code{beginning-of-buffer}). With ! 1444: numeric argument @var{n}, move to @var{n}/10 of the way from the top. ! 1445: @xref{Arguments}, for more information on numeric arguments.@refill ! 1446: @item M-> ! 1447: Move to the end of the buffer (@code{end-of-buffer}). ! 1448: @item M-x goto-char ! 1449: Read a number @var{n} and move cursor to character number @var{n}. ! 1450: Position 1 is the beginning of the buffer. ! 1451: @item M-x goto-line ! 1452: Read a number @var{n} and move cursor to line number @var{n}. Line 1 ! 1453: is the beginning of the buffer. ! 1454: @item C-x C-n ! 1455: @findex set-goal-column ! 1456: Use the current column of point as the @dfn{semipermanent goal column} for ! 1457: @kbd{C-n} and @kbd{C-p} (@code{set-goal-column}). Henceforth, those ! 1458: commands always move to this column in each line moved into, or as ! 1459: close as possible given the contents of the line. This goal column remains ! 1460: in effect until canceled. ! 1461: @item C-u C-x C-n ! 1462: Cancel the goal column. Henceforth, @kbd{C-n} and @kbd{C-p} once ! 1463: again try to avoid changing the horizontal position, as usual. ! 1464: @end table ! 1465: ! 1466: @vindex track-eol ! 1467: If you set the variable @code{track-eol} to a non-@code{nil} value, then ! 1468: @kbd{C-n} and @kbd{C-p} when at the end of the starting line move to the ! 1469: end of the line. Normally, @code{track-eol} is @code{nil}. ! 1470: ! 1471: @section Erasing Text ! 1472: ! 1473: @table @kbd ! 1474: @item @key{DEL} ! 1475: Delete the character before the cursor (@code{delete-backward-char}). ! 1476: @item C-d ! 1477: Delete the character after the cursor (@code{delete-char}). ! 1478: @item C-k ! 1479: Kill to the end of the line (@code{kill-line}). ! 1480: @item M-d ! 1481: Kill forward to the end of the next word (@code{kill-word}). ! 1482: @item M-@key{DEL} ! 1483: Kill back to the beginning of the previous word ! 1484: (@code{backward-kill-word}). ! 1485: @end table ! 1486: ! 1487: You already know about the @key{DEL} key which deletes the character ! 1488: before the cursor. Another key, @kbd{Control-d}, deletes the character ! 1489: after the cursor, causing the rest of the text on the line to shift left. ! 1490: If @kbd{Control-d} is typed at the end of a line, that line and the next ! 1491: line are joined together. ! 1492: ! 1493: To erase a larger amount of text, use the @kbd{Control-k} key, which ! 1494: kills a line at a time. If @kbd{C-k} is done at the beginning or middle of ! 1495: a line, it kills all the text up to the end of the line. If @kbd{C-k} is ! 1496: done at the end of a line, it joins that line and the next line. ! 1497: ! 1498: @xref{Killing}, for more flexible ways of killing text. ! 1499: ! 1500: @section Files ! 1501: ! 1502: @cindex files ! 1503: The commands above are sufficient for creating and altering text in an ! 1504: Emacs buffer; the more advanced Emacs commands just make things easier. ! 1505: But to keep any text permanently you must put it in a @dfn{file}. Files ! 1506: are named units of text which are stored by the operating system for you to ! 1507: retrieve later by name. To look at or use the contents of a file in any ! 1508: way, including editing the file with Emacs, you must specify the file name. ! 1509: ! 1510: Consider a file named @file{/usr/rms/foo.c}. In Emacs, to begin editing ! 1511: this file, type ! 1512: ! 1513: @example ! 1514: C-x C-f /usr/rms/foo.c @key{RET} ! 1515: @end example ! 1516: ! 1517: @noindent ! 1518: Here the file name is given as an @dfn{argument} to the command @kbd{C-x ! 1519: C-f} (@code{find-file}). That command uses the @dfn{minibuffer} to ! 1520: read the argument, and you type @key{RET} to terminate the argument ! 1521: (@pxref{Minibuffer}).@refill ! 1522: ! 1523: Emacs obeys the command by @dfn{visiting} the file: creating a buffer, ! 1524: copying the contents of the file into the buffer, and then displaying the ! 1525: buffer for you to edit. You can make changes in it, and then @dfn{save} ! 1526: the file by typing @kbd{C-x C-s} (@code{save-buffer}). This makes the ! 1527: changes permanent by copying the altered contents of the buffer back into ! 1528: the file @file{/usr/rms/foo.c}. Until then, the changes are only inside ! 1529: your Emacs, and the file @file{foo.c} is not changed.@refill ! 1530: ! 1531: To create a file, just visit the file with @kbd{C-x C-f} as if it already ! 1532: existed. Emacs will make an empty buffer in which you can insert the text ! 1533: you want to put in the file. When you save your text with @kbd{C-x C-s}, ! 1534: the file will be created. ! 1535: ! 1536: Of course, there is a lot more to learn about using files. @xref{Files}. ! 1537: ! 1538: @section Help ! 1539: ! 1540: If you forget what a key does, you can find out with the Help character, ! 1541: which is @kbd{C-h}. Type @kbd{C-h k} followed by the key you want to know ! 1542: about; for example, @kbd{C-h k C-n} tells you all about what @kbd{C-n} ! 1543: does. @kbd{C-h} is a prefix key; @kbd{C-h k} is just one of its ! 1544: subcommands (the command @code{describe-key}). The other subcommands of ! 1545: @kbd{C-h} provide different kinds of help. Type @kbd{C-h} three times ! 1546: to get a description of all the help facilities. @xref{Help}.@refill ! 1547: ! 1548: @menu ! 1549: * Blank Lines:: Commands to make or delete blank lines. ! 1550: * Continuation Lines:: Lines too wide for the screen. ! 1551: * Position Info:: What page, line, row, or column is point on? ! 1552: * Arguments:: Numeric arguments for repeating a command. ! 1553: @end menu ! 1554: ! 1555: @page ! 1556: @node Blank Lines, Continuation Lines, Basic, Basic ! 1557: @section Blank Lines ! 1558: ! 1559: Here are special commands and techniques for putting in and taking out ! 1560: blank lines. ! 1561: ! 1562: @c widecommands ! 1563: @table @kbd ! 1564: @item C-o ! 1565: Insert one or more blank lines after the cursor (@code{open-line}). ! 1566: @item C-x C-o ! 1567: Delete all but one of many consecutive blank lines ! 1568: (@code{delete-blank-lines}). ! 1569: @end table ! 1570: ! 1571: @kindex C-o ! 1572: @kindex C-x C-o ! 1573: @cindex blank lines ! 1574: @findex open-line ! 1575: @findex delete-blank-lines ! 1576: When you want to insert a new line of text before an existing line, you ! 1577: can do it by typing the new line of text, followed by @key{RET}. However, ! 1578: it may be easier to see what you are doing if you first make a blank line ! 1579: and then insert the desired text into it. This is easy to do using the key ! 1580: @kbd{C-o} (@code{open-line}), which inserts a newline after point but leaves ! 1581: point in front of the newline. After @kbd{C-o}, type the text for the new ! 1582: line. @kbd{C-o F O O} has the same effect as @kbd{F O O @key{RET}}, except for ! 1583: the final location of point. ! 1584: ! 1585: You can make several blank lines by typing @kbd{C-o} several times, or by ! 1586: giving it an argument to tell it how many blank lines to make. ! 1587: @xref{Arguments}, for how. ! 1588: ! 1589: If you have many blank lines in a row and want to get rid of them, use ! 1590: @kbd{C-x C-o} (@code{delete-blank-lines}). When point is on a blank line which ! 1591: is adjacent to at least one other blank line, @kbd{C-x C-o} deletes all but ! 1592: one of the consecutive blank lines, leaving exactly one. With point on a ! 1593: blank line with no other blank line adjacent to it, the sole blank line is ! 1594: deleted, leaving none. When point is on a nonblank line, @kbd{C-x C-o} ! 1595: deletes any blank lines following that nonblank line. ! 1596: ! 1597: @node Continuation Lines, Position Info, Blank Lines, Basic ! 1598: @section Continuation Lines ! 1599: ! 1600: @cindex continuation line ! 1601: If you add too many characters to one line, without breaking it with a ! 1602: @key{RET}, the line will grow to occupy two (or more) lines on the screen, ! 1603: with a @samp{\} at the extreme right margin of all but the last of them. ! 1604: The @samp{\} says that the following screen line is not really a distinct ! 1605: line in the text, but just the @dfn{continuation} of a line too long to fit ! 1606: the screen. Sometimes it is nice to have Emacs insert newlines ! 1607: automatically when a line gets too long; for this, use Auto Fill mode ! 1608: (@pxref{Filling}). ! 1609: ! 1610: @vindex truncate-lines ! 1611: @cindex truncation ! 1612: Instead of continuation, long lines can be displayed by @dfn{truncation}. ! 1613: This means that all the characters that do not fit in the width of the ! 1614: screen or window do not appear at all. They remain in the buffer, ! 1615: temporarily invisible. @samp{$} is used in the last column instead of ! 1616: @samp{\} to inform you that truncation is in effect. ! 1617: ! 1618: Continuation can be turned off for a particular buffer by setting the ! 1619: variable @code{truncate-lines} to non-@code{nil} in that buffer. ! 1620: Truncation instead of continuation also happens whenever horizontal ! 1621: scrolling is in use, and optionally whenever side-by-side windows are in ! 1622: use (@pxref{Windows}). Altering the value of @code{truncate-lines} makes ! 1623: it local to the current buffer; until that time, the default value is in ! 1624: effect. The default is initially @code{nil}. @xref{Locals}.@refill ! 1625: ! 1626: @node Position Info, Arguments, Continuation Lines, Basic ! 1627: @section Cursor Position Information ! 1628: ! 1629: If you are accustomed to other display editors, you may be surprised that ! 1630: Emacs does not always display the page number or line number of point in ! 1631: the mode line. This is because the text is stored in a way that makes it ! 1632: difficult to compute this information. Displaying them all the time would ! 1633: be intolerably slow. They are not needed very often in Emacs anyway, ! 1634: but there are commands to compute them and print them. ! 1635: ! 1636: @table @kbd ! 1637: @item M-x what-page ! 1638: Print page number of point, and line number within page. ! 1639: @item M-x what-line ! 1640: Print line number of point in the buffer. ! 1641: @item M-= ! 1642: Print number of lines in the current region (@code{count-lines-region}). ! 1643: @item C-x = ! 1644: Print character code of character after point, character position of ! 1645: point, and column of point (@code{what-cursor-position}). ! 1646: @end table ! 1647: ! 1648: @findex what-page ! 1649: @findex what-line ! 1650: @cindex line number ! 1651: There are two commands for printing line numbers. @kbd{M-x what-line} ! 1652: counts lines from the beginning of the file and prints the line number ! 1653: point is on. The first line of the file is line number 1. These numbers ! 1654: can be used as arguments to @kbd{M-x goto-line}. By contrast, @kbd{M-x ! 1655: what-page} counts pages from the beginning of the file, and counts lines ! 1656: within the page, printing both of them. @xref{Pages}. ! 1657: ! 1658: @kindex M-= ! 1659: @findex count-lines-region ! 1660: While on this subject, we might as well mention @kbd{M-=} (@code{count-lines-region}), ! 1661: which prints the number of lines in the region (@pxref{Mark}). ! 1662: @xref{Pages}, for the command @kbd{C-x l} which counts the lines in the ! 1663: current page. ! 1664: ! 1665: @kindex C-x = ! 1666: @findex what-cursor-position ! 1667: The command @kbd{C-x =} (@code{what-cursor-position}) can be used to find out ! 1668: the column that the cursor is in, and other miscellaneous information about ! 1669: point. It prints a line in the echo area that looks like this: ! 1670: ! 1671: @example ! 1672: Char: x (0170) point=65986 of 563027(12%) x=44 ! 1673: @end example ! 1674: ! 1675: @noindent ! 1676: (In fact, this is the output produced when point is before the @samp{x=44} ! 1677: in the example.) ! 1678: ! 1679: The two values after @samp{Char:} describe the character following point, ! 1680: first by showing it and second by giving its octal character code. ! 1681: ! 1682: @samp{point=} is followed by the position of point expressed as a character ! 1683: count. The front of the buffer counts as position 1, one character later ! 1684: as 2, and so on. The next, larger number is the total number of characters ! 1685: in the buffer. Afterward in parentheses comes the position expressed as a ! 1686: percentage of the total size. ! 1687: ! 1688: @samp{x=} is followed by the horizontal position of point, in columns from the ! 1689: left edge of the window. ! 1690: ! 1691: If the buffer has been narrowed, making some of the text at the beginning and ! 1692: the end temporarily invisible, @kbd{C-x =} prints additional text describing the ! 1693: current visible range. For example, it might say ! 1694: ! 1695: @smallexample ! 1696: Char: x (0170) point=65986 of 563025(12%) <65102 - 68533> x=44 ! 1697: @end smallexample ! 1698: ! 1699: @noindent ! 1700: where the two extra numbers give the smallest and largest character position ! 1701: that point is allowed to assume. The characters between those two positions ! 1702: are the visible ones. @xref{Narrowing}. ! 1703: ! 1704: If point is at the end of the buffer (or the end of the visible part), ! 1705: @kbd{C-x =} omits any description of the character after point. ! 1706: The output looks like ! 1707: ! 1708: @smallexample ! 1709: point=563026 of 563025(100%) x=0 ! 1710: @end smallexample ! 1711: ! 1712: @node Arguments,, Position Info, Basic ! 1713: @section Numeric Arguments ! 1714: @cindex numeric arguments ! 1715: ! 1716: Any Emacs command can be given a @dfn{numeric argument}. Some commands ! 1717: interpret the argument as a repetition count. For example, giving an ! 1718: argument of ten to the key @kbd{C-f} (the command @code{forward-char}, move ! 1719: forward one character) moves forward ten characters. With these commands, ! 1720: no argument is equivalent to an argument of one. Negative arguments are ! 1721: allowed. Often they tell a command to move or act backwards. ! 1722: ! 1723: @kindex M-1 ! 1724: @kindex M-@t{-} ! 1725: @findex digit-argument ! 1726: @findex negative-argument ! 1727: If your terminal keyboard has a @key{META} key, the easiest way to ! 1728: specify a numeric argument is to type digits and/or a minus sign while ! 1729: holding down the the @key{META} key. For example, ! 1730: @example ! 1731: M-5 C-n ! 1732: @end example ! 1733: @noindent ! 1734: would move down five lines. The characters @kbd{Meta-1}, @kbd{Meta-2}, and ! 1735: so on, as well as @kbd{Meta--}, do this because they are keys bound to ! 1736: commands (@code{digit-argument} and @code{negative-argument}) that are ! 1737: defined to contribute to an argument for the next command. ! 1738: ! 1739: @kindex C-u ! 1740: @findex universal-argument ! 1741: Another way of specifying an argument is to use the @kbd{C-u} ! 1742: (@code{universal-argument}) command followed by the digits of the argument. ! 1743: With @kbd{C-u}, you can type the argument digits without holding ! 1744: down shift keys. To type a negative argument, start with a minus sign. ! 1745: Just a minus sign normally means @minus{}1. @kbd{C-u} works on all terminals. ! 1746: ! 1747: @kbd{C-u} followed by a character which is neither a digit nor a minus ! 1748: sign has the special meaning of ``multiply by four''. It multiplies the ! 1749: argument for the next command by four. @kbd{C-u} twice multiplies it by ! 1750: sixteen. Thus, @kbd{C-u C-u C-f} moves forward sixteen characters. This ! 1751: is a good way to move forward ``fast'', since it moves about 1/5 of a line ! 1752: in the usual size screen. Other useful combinations are @kbd{C-u C-n}, ! 1753: @kbd{C-u C-u C-n} (move down a good fraction of a screen), @kbd{C-u C-u ! 1754: C-o} (make ``a lot'' of blank lines), and @kbd{C-u C-k} (kill four ! 1755: lines).@refill ! 1756: ! 1757: Some commands care only about whether there is an argument, and not about ! 1758: its value. For example, the command @kbd{M-q} (@code{fill-paragraph}) with ! 1759: no argument fills text; with an argument, it justifies the text as well. ! 1760: (@xref{Filling}, for more information on @kbd{M-q}.) Just @kbd{C-u} is a ! 1761: handy way of providing an argument for such commands. ! 1762: ! 1763: Some commands use the value of the argument as a repeat count, but do ! 1764: something peculiar when there is no argument. For example, the command ! 1765: @kbd{C-k} (@code{kill-line}) with argument @var{n} kills @var{n} lines, ! 1766: including their terminating newlines. But @kbd{C-k} with no argument is ! 1767: special: it kills the text up to the next newline, or, if point is right at ! 1768: the end of the line, it kills the newline itself. Thus, two @kbd{C-k} ! 1769: commands with no arguments can kill a nonblank line, just like @kbd{C-k} ! 1770: with an argument of one. (@xref{Killing}, for more information on ! 1771: @kbd{C-k}.)@refill ! 1772: ! 1773: A few commands treat a plain @kbd{C-u} differently from an ordinary ! 1774: argument. A few others may treat an argument of just a minus sign ! 1775: differently from an argument of @minus{}1. These unusual cases will be described ! 1776: when they come up; they are always for reasons of convenience of use of the ! 1777: individual command. ! 1778: ! 1779: @c section Autoarg Mode ! 1780: @ignore ! 1781: @cindex autoarg mode ! 1782: Users of ASCII keyboards may prefer to use Autoarg mode. Autoarg mode ! 1783: means that you don't need to type C-U to specify a numeric argument. ! 1784: Instead, you type just the digits. Digits followed by an ordinary ! 1785: inserting character are themselves inserted, but digits followed by an ! 1786: Escape or Control character serve as an argument to it and are not ! 1787: inserted. A minus sign can also be part of an argument, but only at the ! 1788: beginning. If you type a minus sign following some digits, both the digits ! 1789: and the minus sign are inserted. ! 1790: ! 1791: To use Autoarg mode, set the variable Autoarg Mode nonzero. ! 1792: @xref{Variables}. ! 1793: ! 1794: Autoargument digits echo at the bottom of the screen; the first nondigit ! 1795: causes them to be inserted or uses them as an argument. To insert some ! 1796: digits and nothing else, you must follow them with a Space and then rub it ! 1797: out. C-G cancels the digits, while Delete inserts them all and then rubs ! 1798: out the last. ! 1799: @end ignore ! 1800: ! 1801: @node Undo, Minibuffer, Basic, Top ! 1802: @chapter Undoing Changes ! 1803: @cindex undo ! 1804: @cindex mistakes, correcting ! 1805: ! 1806: Emacs allows all changes made in the text of a buffer to be undone, ! 1807: up to a certain amount of change (8000 characters). Each buffer records ! 1808: changes individually, and the undo command always applies to the ! 1809: current buffer. Usually each editing command makes a separate entry ! 1810: in the undo records, but some commands such as @code{query-replace} ! 1811: make many entries, and very simple commands such as self-inserting ! 1812: characters are often grouped to make undoing less tedious. ! 1813: ! 1814: @table @kbd ! 1815: @item C-x u ! 1816: Undo one batch of changes (usually, one command worth) (@code{undo}). ! 1817: @item C-_ ! 1818: The same. ! 1819: @end table ! 1820: ! 1821: @kindex C-x u ! 1822: @kindex C-_ ! 1823: @findex undo ! 1824: The command @kbd{C-x u} or @kbd{C-_} is how you undo. The first time you give ! 1825: this command, it undoes the last change. Point moves to the text ! 1826: affected by the undo, so you can see what was undone. ! 1827: ! 1828: Consecutive repetitions of the @kbd{C-_} or @kbd{C-x u} commands undo earlier ! 1829: and earlier changes, back to the limit of what has been recorded. If all ! 1830: recorded changes have already been undone, the undo command prints an error ! 1831: message and does nothing. ! 1832: ! 1833: Any command other than an undo command breaks the sequence of undo ! 1834: commands. Starting at this moment, the previous undo commands are ! 1835: considered ordinary changes that can themselves be undone. Thus, you can ! 1836: redo changes you have undone by typing @kbd{C-f} or any other command that ! 1837: will have no important effect, and then using more undo commands. ! 1838: ! 1839: If you notice that a buffer has been modified accidentally, the easiest ! 1840: way to recover is to type @kbd{C-_} repeatedly until the stars disappear ! 1841: from the front of the mode line. At this time, all the modifications you ! 1842: made have been cancelled. If you do not remember whether you changed the ! 1843: buffer deliberately, type @kbd{C-_} once, and when you see the last change ! 1844: you made undone, you will remember why you made it. If it was an accident, ! 1845: leave it undone. If it was deliberate, redo the change as described in the ! 1846: preceding paragraph. ! 1847: ! 1848: Whenever an undo command makes the stars disappear from the mode line, ! 1849: it means that the buffer contents are the same as they were when the ! 1850: file was last read in or saved. ! 1851: ! 1852: Not all buffers record undo information. Buffers whose names start with ! 1853: spaces don't; these buffers are used internally by Emacs and its extensions ! 1854: to hold text that users don't normally look at or edit. Also, minibuffers, ! 1855: help buffers and documentation buffers don't record undo information. ! 1856: ! 1857: At most 8000 or so characters of deleted or modified text can be ! 1858: remembered in any one buffer for reinsertion by the undo command. Also, ! 1859: there is a limit on the number of individual insert, delete or change ! 1860: actions that can be remembered. ! 1861: ! 1862: The reason the @code{undo} command has two keys, @kbd{C-x u} and @kbd{C-_}, set ! 1863: up to run it is that it is worthy of a single-character key, but the way to ! 1864: type @kbd{C-_} on some keyboards is not obvious. @kbd{C-x u} is an alternative ! 1865: you can type in the same fashion on any terminal. ! 1866: ! 1867: @node Minibuffer, M-x, Undo, Top ! 1868: @chapter The Minibuffer ! 1869: @cindex minibuffer ! 1870: ! 1871: The @dfn{minibuffer} is the facility used by Emacs commands to read ! 1872: arguments more complicated than a single number. Minibuffer arguments can ! 1873: be file names, buffer names, Lisp function names, Emacs command names, Lisp ! 1874: expressions, and many other things, depending on the command reading the ! 1875: argument. The usual Emacs editing commands can be used in the minibuffer ! 1876: to edit the argument. ! 1877: ! 1878: @cindex prompt ! 1879: When the minibuffer is in use, it appears in the echo area, and the ! 1880: terminal's cursor moves there. The beginning of the minibuffer line ! 1881: displays a @dfn{prompt} which says what kind of input you should supply and ! 1882: how it will be used. Often this prompt is derived from the name of the ! 1883: command that the argument is for. The prompt normally ends with a colon. ! 1884: ! 1885: @cindex default argument ! 1886: Sometimes a @dfn{default argument} appears in parentheses after the ! 1887: colon; it too is part of the prompt. The default will be used as the ! 1888: argument value if you enter an empty argument (e.g., just type @key{RET}). ! 1889: For example, commands that read buffer names always show a default, which ! 1890: is the name of the buffer that will be used if you type just @key{RET}. ! 1891: ! 1892: @kindex C-g ! 1893: The simplest way to give a minibuffer argument is to type the text you ! 1894: want, terminated by @key{RET} which exits the minibuffer. You can get out ! 1895: of the minibuffer, canceling the command that it was for, by typing ! 1896: @kbd{C-g}. ! 1897: ! 1898: Since the minibuffer uses the screen space of the echo area, it can ! 1899: conflict with other ways Emacs customarily uses the echo area. Here is how ! 1900: Emacs handles such conflicts: ! 1901: ! 1902: @itemize @bullet ! 1903: @item ! 1904: If a command gets an error while you are in the minibuffer, this does ! 1905: not cancel the minibuffer. However, the echo area is needed for the ! 1906: error message and therefore the minibuffer itself is hidden for a ! 1907: while. It comes back after a few seconds, or as soon as you type ! 1908: anything. ! 1909: ! 1910: @item ! 1911: If in the minibuffer you use a command whose purpose is to print a ! 1912: message in the echo area, such as @kbd{C-x =}, the message is printed ! 1913: normally, and the minibuffer is hidden for a while. It comes back ! 1914: after a few seconds, or as soon as you type anything. ! 1915: ! 1916: @item ! 1917: Echoing of keystrokes does not take place while the minibuffer is in ! 1918: use. ! 1919: @end itemize ! 1920: ! 1921: @menu ! 1922: * File: Minibuffer File. Entering file names with the minibuffer. ! 1923: * Edit: Minibuffer Edit. How to edit in the minibuffer. ! 1924: * Completion:: An abbreviation facility for minibuffer input. ! 1925: * Repetition:: Re-executing commands that used the minibuffer. ! 1926: @end menu ! 1927: ! 1928: @node Minibuffer File, Minibuffer Edit, Minibuffer, Minibuffer ! 1929: @section Minibuffers for File Names ! 1930: ! 1931: Sometimes the minibuffer starts out with text in it. For example, when ! 1932: you are supposed to give a file name, the minibuffer starts out containing ! 1933: the @dfn{default directory}, which ends with a slash. This is to inform ! 1934: you which directory the file will be found in if you do not specify a ! 1935: directory. For example, the minibuffer might start out with ! 1936: ! 1937: @example ! 1938: Find File: /u2/emacs/src/ ! 1939: @end example ! 1940: ! 1941: @noindent ! 1942: where @samp{Find File:@: } is the prompt. Typing @kbd{buffer.c} specifies ! 1943: the file @file{/u2/emacs/src/buffer.c}. To find files in nearby ! 1944: directories, use @kbd{..}; thus, if you type @kbd{../lisp/simple.el}, the ! 1945: file that you visit will be the one named @file{/u2/emacs/lisp/simple.el}. ! 1946: Alternatively, you can kill with @kbd{M-@key{DEL}} the directory names you ! 1947: don't want (@pxref{Words}).@refill ! 1948: ! 1949: You can also type an absolute file name, one starting with a slash or a ! 1950: tilde, ignoring the default directory. For example, to find the file ! 1951: @file{/etc/termcap}, just type the name, giving ! 1952: ! 1953: @example ! 1954: Find File: /u2/emacs/src//etc/termcap ! 1955: @end example ! 1956: ! 1957: @noindent ! 1958: Two slashes in a row are not normally meaningful in Unix file names, but ! 1959: they are allowed in GNU Emacs. They mean, ``ignore everything before the ! 1960: second slash in the pair.'' Thus, @samp{/u2/emacs/src/} is ignored, and ! 1961: you get the file @file{/etc/termcap}. ! 1962: ! 1963: @vindex insert-default-directory ! 1964: If you set @code{insert-default-directory} to @code{nil}, the default directory ! 1965: is not inserted in the minibuffer. This way, the minibuffer starts out ! 1966: empty. But the name you type, if relative, is still interpreted with ! 1967: respect to the same default directory. ! 1968: ! 1969: @node Minibuffer Edit, Completion, Minibuffer File, Minibuffer ! 1970: @section Editing in the Minibuffer ! 1971: ! 1972: The minibuffer is an Emacs buffer (albeit a peculiar one), and the usual ! 1973: Emacs commands are available for editing the text of an argument you are ! 1974: entering. ! 1975: ! 1976: Since @key{RET} in the minibuffer is defined to exit the minibuffer, ! 1977: inserting a newline into the minibuffer must be done with @kbd{C-o} or with ! 1978: @kbd{C-q @key{LFD}}. (Recall that a newline is really the @key{LFD} ! 1979: character.) ! 1980: ! 1981: The minibuffer has its own window which always has space on the screen ! 1982: but acts as if it were not there when the minibuffer is not in use. When ! 1983: the minibuffer is in use, its window is just like the others; you can ! 1984: switch to another window with @kbd{C-x o}, edit text in other windows and ! 1985: perhaps even visit more files, before returning to the minibuffer to submit ! 1986: the argument. You can kill text in another window, return to the ! 1987: minibuffer window, and then yank the text to use it in the argument. ! 1988: @xref{Windows}. ! 1989: ! 1990: There are some restrictions on the use of the minibuffer window, however. ! 1991: You cannot switch buffers in it---the minibuffer and its window are ! 1992: permanently attached. Also, you cannot split or kill the minibuffer ! 1993: window. But you can make it taller in the normal fashion with @kbd{C-x ^}. ! 1994: ! 1995: @kindex C-M-v ! 1996: If while in the minibuffer you issue a command that displays help text ! 1997: of any sort in another window, then that window is identified as the ! 1998: one to scroll if you type @kbd{C-M-v} while in the minibuffer. This ! 1999: lasts until you exit the minibuffer. This feature comes into play ! 2000: if a completing minibuffer gives you a list of possible completions. ! 2001: ! 2002: Recursive use of the minibuffer is supported by Emacs. However, it is ! 2003: easy to do this by accident (because of autorepeating keyboards, for ! 2004: example) and get confused. Therefore, most Emacs commands that use the ! 2005: minibuffer refuse to operate if the minibuffer window is selected. If the ! 2006: minibuffer is active but you have switched to a different window, recursive ! 2007: use of the minibuffer is allowed---if you know enough to try to do this, ! 2008: you probably will not get confused. ! 2009: ! 2010: @vindex enable-recursive-minibuffers ! 2011: If you set the variable @code{enable-recursive-minibuffers} to be ! 2012: non-@code{nil}, recursive use of the minibuffer is always allowed. ! 2013: ! 2014: @node Completion, Repetition, Minibuffer Edit, Minibuffer ! 2015: @section Completion ! 2016: @cindex completion ! 2017: ! 2018: When appropriate, the minibuffer provides a @dfn{completion} facility. ! 2019: This means that you type enough of the argument to determine the rest, ! 2020: based on Emacs's knowledge of which arguments make sense, and Emacs visibly ! 2021: fills in the rest, or as much as can be determined from the part you have ! 2022: typed. ! 2023: ! 2024: When completion is available, certain keys---@key{TAB}, @key{RET}, and @key{SPC}---are ! 2025: redefined to complete an abbreviation present in the minibuffer into a ! 2026: longer string that it stands for, by matching it against a set of ! 2027: @dfn{completion alternatives} provided by the command reading the argument. ! 2028: @kbd{?} is defined to display a list of possible completions of what you ! 2029: have inserted. ! 2030: ! 2031: For example, when the minibuffer is being used by @kbd{Meta-x} to read ! 2032: the name of a command, it is given a list of all available Emacs command ! 2033: names to complete against. The completion keys match the text in the ! 2034: minibuffer against all the command names, find any additional characters of ! 2035: the name that are implied by the ones already present in the minibuffer, ! 2036: and add those characters to the ones you have given. ! 2037: ! 2038: Case is normally significant in completion, because it is significant in ! 2039: most of the names that you can complete (buffer names, file names and ! 2040: command names). Thus, @samp{fo} will not complete to @samp{Foo}. When you ! 2041: are completing a name in which case does not matter, case may be ignored ! 2042: for completion's sake if the program said to do so. ! 2043: ! 2044: @subsection Completion Example ! 2045: ! 2046: @kindex TAB ! 2047: @findex minibuffer-complete ! 2048: A concrete example may help here. If you type @kbd{Meta-x au @key{TAB}}, ! 2049: the @key{TAB} looks for alternatives (in this case, command names) that ! 2050: start with @samp{au}. There are only two: @code{auto-fill-mode} and ! 2051: @code{auto-save-mode}. These are the same as far as @code{auto-}, so the ! 2052: @samp{au} in the minibuffer changes to @samp{auto-}.@refill ! 2053: ! 2054: If you type @key{TAB} again immediately, there are multiple possibilities ! 2055: for the very next character---it could be @samp{s} or @samp{f}---so no more ! 2056: characters are added; but a list of all possible completions is displayed ! 2057: in another window. ! 2058: ! 2059: If you go on to type @kbd{f @key{TAB}}, this @key{TAB} sees ! 2060: @samp{auto-f}. The only command name starting this way is ! 2061: @code{auto-fill-mode}, so completion inserts the rest of that. You ! 2062: now have @samp{auto-fill-mode} in the minibuffer after typing just @kbd{au ! 2063: @key{TAB} f @key{TAB}}. Note that @key{TAB} has this effect because in the ! 2064: minibuffer it is bound to the function @code{minibuffer-complete} when ! 2065: completion is supposed to be done.@refill ! 2066: ! 2067: @subsection Completion Commands ! 2068: ! 2069: Here is a list of all the completion commands, defined in the minibuffer ! 2070: when completion is available. ! 2071: ! 2072: @table @kbd ! 2073: @item @key{TAB} ! 2074: Complete the text in the minibuffer as much as possible @* ! 2075: (@code{minibuffer-complete}). ! 2076: @item @key{SPC} ! 2077: Complete the text in the minibuffer but don't add or fill out more ! 2078: than one word (@code{minibuffer-complete-word}). ! 2079: @item @key{RET} ! 2080: Submit the text in the minibuffer as the argument, possibly completing ! 2081: first as described below (@code{minibuffer-complete-and-exit}). ! 2082: @item ? ! 2083: Print a list of all possible completions of the text in the minibuffer ! 2084: (@code{minibuffer-list-completions}). ! 2085: @end table ! 2086: ! 2087: @kindex SPC ! 2088: @findex minibuffer-complete-word ! 2089: @key{SPC} completes much like @key{TAB}, but never goes beyond the ! 2090: next hyphen or space. If you have @samp{auto-f} in the minibuffer and type ! 2091: @key{SPC}, it finds that the completion is @samp{auto-fill-mode}, but it ! 2092: stops completing after @samp{fill-}. This gives @samp{auto-fill-}. ! 2093: Another @key{SPC} at this point completes all the way to ! 2094: @samp{auto-fill-mode}. @key{SPC} in the minibuffer runs the function ! 2095: @code{minibuffer-complete-word} when completion is available.@refill ! 2096: ! 2097: There are three different ways that @key{RET} can work in completing ! 2098: minibuffers, depending on how the argument will be used. ! 2099: ! 2100: @itemize @bullet ! 2101: @item ! 2102: @dfn{Strict} completion is used when it is meaningless to give any ! 2103: argument except one of the known alternatives. For example, when ! 2104: @kbd{C-x k} reads the name of a buffer to kill, it is meaningless to ! 2105: give anything but the name of an existing buffer. In strict ! 2106: completion, @key{RET} refuses to exit if the text in the minibuffer ! 2107: does not complete to an exact match. ! 2108: ! 2109: @item ! 2110: @dfn{Cautious} completion is similar to strict completion, except that ! 2111: @key{RET} exits only if the text was an exact match already, not ! 2112: needing completion. If the text is not an exact match, @key{RET} does ! 2113: not exit, but it does complete the text. If it completes to an exact ! 2114: match, a second @key{RET} will exit. ! 2115: ! 2116: Cautious completion is used for reading file names for files that must ! 2117: already exist. ! 2118: ! 2119: @item ! 2120: @dfn{Permissive} completion is used when any string whatever is ! 2121: meaningful, and the list of completion alternatives is just a guide. ! 2122: For example, when @kbd{C-x C-f} reads the name of a file to visit, any ! 2123: file name is allowed, in case you want to create a file. In ! 2124: permissive completion, @key{RET} takes the text in the minibuffer ! 2125: exactly as given, without completing it. ! 2126: @end itemize ! 2127: ! 2128: The completion commands display a list of all possible completions in a ! 2129: window whenever there is more than one possibility for the very next ! 2130: character. Also, typing @kbd{?} explicitly requests such a list. The ! 2131: list of completions counts as help text, so @kbd{C-M-v} typed in the ! 2132: minibuffer scrolls the list. ! 2133: ! 2134: @vindex completion-ignored-extensions ! 2135: When completion is done on file names, certain file names are usually ! 2136: ignored. The variable @code{completion-ignored-extensions} contains a list ! 2137: of strings; a file whose name ends in any of those strings is ignored as a ! 2138: possible completion. The standard value of this variable has several ! 2139: elements including @code{".o"}, @code{".elc"}, @code{".dvi"} and @code{"~"}. ! 2140: The effect is that, for example, @samp{foo} can complete to @samp{foo.c} ! 2141: even though @samp{foo.o} exists as well. If the only possible completions ! 2142: are files that end in ``ignored'' strings, then they are not ignored.@refill ! 2143: ! 2144: @vindex completion-auto-help ! 2145: Normally, a completion command that finds the next character is undetermined ! 2146: automatically displays a list of all possible completions. If the variable ! 2147: @code{completion-auto-help} is set to @code{nil}, this does not happen, ! 2148: and you must type @kbd{?} to display the possible completions. ! 2149: ! 2150: @node Repetition,, Completion, Minibuffer ! 2151: @section Repeating Minibuffer Commands ! 2152: @cindex command history ! 2153: @cindex history of commands ! 2154: ! 2155: Every command that uses the minibuffer at least once is recorded on a ! 2156: special history list, together with the values of the minibuffer arguments, ! 2157: so that you can repeat the command easily. In particular, every ! 2158: use of @kbd{Meta-x} is recorded, since @kbd{M-x} uses the minibuffer to ! 2159: read the command name. ! 2160: ! 2161: @findex list-command-history ! 2162: @c widecommands ! 2163: @table @kbd ! 2164: @item C-x @key{ESC} ! 2165: Re-execute a recent minibuffer command @*(@code{repeat-complex-command}). ! 2166: @item M-p ! 2167: Within @kbd{C-x @key{ESC}}, move to previous recorded command ! 2168: (@code{previous-complex-command}). ! 2169: @item M-n ! 2170: Within @kbd{C-x @key{ESC}}, move to the next (more recent) recorded ! 2171: command (@code{next-complex-command}). ! 2172: @item M-x list-command-history ! 2173: Display the entire command history, showing all the commands ! 2174: @kbd{C-x @key{ESC}} can repeat, most recent first. ! 2175: @end table ! 2176: ! 2177: @kindex C-x ESC ! 2178: @findex repeat-complex-command ! 2179: @kbd{C-x @key{ESC}} is used to re-execute a recent minibuffer-using ! 2180: command. With no argument, it repeats the last such command. A numeric ! 2181: argument specifies which command to repeat; one means the last one, and ! 2182: larger numbers specify earlier ones. ! 2183: ! 2184: @kbd{C-x @key{ESC}} works by turning the previous command into a Lisp ! 2185: expression and then entering a minibuffer initialized with the text for ! 2186: that expression. If you type just @key{RET}, the command is repeated as ! 2187: before. You can also change the command by editing the Lisp expression. ! 2188: Whatever expression you finally submit is what will be executed. The ! 2189: repeated command is added to the front of the command history unless it is ! 2190: identical to the most recently executed command already there. ! 2191: ! 2192: Even if you don't understand Lisp syntax, it will probably be obvious ! 2193: which command is displayed for repetition. If you do not change the text, ! 2194: you can be sure it will repeat exactly as before. ! 2195: ! 2196: @kindex M-n ! 2197: @kindex M-p ! 2198: @findex next-complex-command ! 2199: @findex previous-complex-command ! 2200: Once inside the minibuffer for @kbd{C-x @key{ESC}}, if the command shown ! 2201: to you is not the one you want to repeat, you can move around the list of ! 2202: previous commands using @kbd{M-n} and @kbd{M-p}. @kbd{M-p} replaces the ! 2203: contents of the minibuffer with the next earlier recorded command, and ! 2204: @kbd{M-n} replaces them with the next later command. After finding the ! 2205: desired previous command, you can edit its expression as usual and then ! 2206: resubmit it by typing @key{RET} as usual. Any editing you have done on the ! 2207: command to be repeated is lost if you use @kbd{M-n} or @kbd{M-p}. ! 2208: ! 2209: @kbd{M-p} is more useful than @kbd{M-n}, since more often you will ! 2210: initially request to repeat the most recent command and then decide to ! 2211: repeat an older one instead. These keys are specially defined within ! 2212: @kbd{C-x @key{ESC}} to run the commands @code{previous-complex-command} and ! 2213: @code{next-complex-command}. ! 2214: ! 2215: @vindex command-history ! 2216: The list of previous minibuffer-using commands is stored as a Lisp list ! 2217: in the variable @code{command-history}. Each element is a Lisp expression ! 2218: which describes one command and its arguments. Lisp programs can reexecute ! 2219: a command by feeding the corresponding @code{command-history} element to ! 2220: @code{eval}. ! 2221: ! 2222: @node M-x, Help, Minibuffer, Top ! 2223: @chapter Running Commands by Name ! 2224: ! 2225: The Emacs commands that are used often or that must be quick to type are ! 2226: bound to keys---short sequences of characters---for convenient use. Other ! 2227: Emacs commands that do not need to be brief are not bound to keys; to run ! 2228: them, you must refer to them by name. ! 2229: ! 2230: A command name is, by convention, made up of one or more words, separated ! 2231: by hyphens; for example, @code{auto-fill-mode} or @code{manual-entry}. The ! 2232: use of English words makes the command name easier to remember than a key ! 2233: made up of obscure characters, even though it is more characters to type. ! 2234: Any command can be run by name, even if it is also runnable by keys. ! 2235: ! 2236: @kindex M-x ! 2237: @cindex minibuffer ! 2238: The way to run a command by name is to start with @kbd{M-x}, type the ! 2239: command name, and finish it with @key{RET}. @kbd{M-x} uses the minibuffer ! 2240: to read the command name. @key{RET} exits the minibuffer and runs the ! 2241: command. ! 2242: ! 2243: Emacs uses the minibuffer for reading input for many different purposes; ! 2244: on this occasion, the string @samp{M-x} is displayed at the beginning of ! 2245: the minibuffer as a @dfn{prompt} to remind you that your input should be ! 2246: the name of a command to be run. @xref{Minibuffer}, for full information ! 2247: on the features of the minibuffer. ! 2248: ! 2249: You can use completion to enter the command name. For example, the ! 2250: command @code{forward-char} can be invoked by name by typing ! 2251: ! 2252: @example ! 2253: M-x forward-char @key{RET} ! 2254: ! 2255: @exdent or ! 2256: ! 2257: M-x fo @key{TAB} c @key{RET} ! 2258: @end example ! 2259: ! 2260: @noindent ! 2261: Note that @code{forward-char} is the same command that you invoke with ! 2262: the key @kbd{C-f}. Any command (interactively callable function) defined ! 2263: in Emacs can be called by its name using @kbd{M-x} whether or not any ! 2264: keys are bound to it. ! 2265: ! 2266: If you type @kbd{C-g} while the command name is being read, you cancel ! 2267: the @kbd{M-x} command and get out of the minibuffer, ending up at top level. ! 2268: ! 2269: To pass a numeric argument to the command you are invoking with ! 2270: @kbd{M-x}, specify the numeric argument before the @kbd{M-x}. @kbd{M-x} ! 2271: passes the argument along to the function which it calls. The argument ! 2272: value appears in the prompt while the command name is being read. ! 2273: ! 2274: Normally, when describing a command that is run by name, we omit the ! 2275: @key{RET} that is needed to terminate the name. Thus we might speak of ! 2276: @kbd{M-x auto-fill-mode} rather than @kbd{M-x auto-fill-mode @key{RET}}. ! 2277: We mention the @key{RET} only when there is a need to emphasize its ! 2278: presence, such as when describing a sequence of input that contains a ! 2279: command name and arguments that follow it. ! 2280: ! 2281: @findex execute-extended-command ! 2282: @kbd{M-x} is defined to run the command @code{execute-extended-command}, ! 2283: which is responsible for reading the name of another command and invoking ! 2284: it. ! 2285: ! 2286: @node Help, Mark, M-x, Top ! 2287: @chapter Help ! 2288: @kindex Help ! 2289: @cindex help ! 2290: @cindex self-documentation ! 2291: ! 2292: Emacs provides extensive help features which revolve around a single ! 2293: character, @kbd{C-h}. @kbd{C-h} is a prefix key that is used only for ! 2294: documentation-printing commands. The characters that you can type after ! 2295: @kbd{C-h} are called @dfn{help options}. One help option is @kbd{C-h}; ! 2296: that is how you ask for help about using @kbd{C-h}. ! 2297: ! 2298: @kbd{C-h C-h} prints a list of the possible help options, and then asks ! 2299: you to go ahead and type the option. It prompts with a string ! 2300: ! 2301: @smallexample ! 2302: A, B, C, F, I, K, L, M, N, S, T, V, W, C-c, C-d, C-n, C-w or C-h for more help: ! 2303: @end smallexample ! 2304: ! 2305: @noindent ! 2306: and you should type one of those characters. ! 2307: ! 2308: Typing a third @kbd{C-h} displays a description of what the options mean; ! 2309: it still waits for you to type an option. To cancel, type @kbd{C-g}. ! 2310: ! 2311: Here is a summary of the defined help commands. ! 2312: ! 2313: @table @kbd ! 2314: @item C-h a @var{string} @key{RET} ! 2315: Display list of commands whose names contain @var{string} ! 2316: (@code{command-apropos}). ! 2317: @item C-h b ! 2318: Display a table of all key bindings in effect now; local bindings of ! 2319: the current major mode first, followed by all global bindings ! 2320: (@code{describe-bindings}). ! 2321: @item C-h c @var{key} ! 2322: Print the name of the command that @var{key} runs (@code{describe-key-briefly}). ! 2323: @kbd{c} is for `character'. For more extensive information on @var{key}, ! 2324: use @kbd{C-h k}. ! 2325: @item C-h f @var{function} @key{RET} ! 2326: Display documentation on the Lisp function named @var{function} ! 2327: (@code{describe-function}). Note that commands are Lisp functions, so ! 2328: a command name may be used. ! 2329: @item C-h i ! 2330: Run Info, the program for browsing documentation files (@code{info}). ! 2331: The complete Emacs manual is available on-line in Info. ! 2332: @item C-h k @var{key} ! 2333: Display name and documentation of the command @var{key} runs (@code{describe-key}). ! 2334: @item C-h l ! 2335: Display a description of the last 100 characters you typed ! 2336: (@code{view-lossage}). ! 2337: @item C-h m ! 2338: Display documentation of the current major mode (@code{describe-mode}). ! 2339: @item C-h n ! 2340: Display documentation of Emacs changes, most recent first ! 2341: (@code{view-emacs-news}). ! 2342: @item C-h s ! 2343: Display current contents of the syntax table, plus an explanation of ! 2344: what they mean (@code{describe-syntax}). ! 2345: @item C-h t ! 2346: Display the Emacs tutorial (@code{help-with-tutorial}). ! 2347: @item C-h v @var{var} @key{RET} ! 2348: Display the documentation of the Lisp variable @var{var} ! 2349: (@code{describe-variable}). ! 2350: @item C-h w @var{command} @key{RET} ! 2351: Print which keys run the command named @var{command} (@code{where-is}). ! 2352: @end table ! 2353: ! 2354: @section Documentation for a Key ! 2355: ! 2356: @kindex C-h c ! 2357: @findex describe-key-briefly ! 2358: The most basic @kbd{C-h} options are @kbd{C-h c} ! 2359: (@code{describe-key-briefly}) and @kbd{C-h k} (@code{describe-key}). ! 2360: @kbd{C-h c @var{key}} prints in the echo area the name of the command that ! 2361: @var{key} is bound to. For example, @kbd{C-h c C-f} prints ! 2362: @samp{forward-char}. Since command names are chosen to describe what the ! 2363: command does, this is a good way to get a very brief description of what ! 2364: @var{key} does.@refill ! 2365: ! 2366: @kindex C-h k ! 2367: @findex describe-key ! 2368: @kbd{C-h k @var{key}} is similar but gives more information. It displays ! 2369: the documentation string of the command @var{key} is bound to as well as ! 2370: its name. This is too big for the echo area, so a window is used for the ! 2371: display. ! 2372: ! 2373: @section Help by Command or Variable Name ! 2374: ! 2375: @kindex C-h f ! 2376: @findex describe-function ! 2377: @kbd{C-h f} (@code{describe-function}) reads the name of a Lisp function ! 2378: using the minibuffer, then displays that function's documentation string ! 2379: in a window. Since commands are Lisp functions, you can use this to get ! 2380: the documentation of a command that is known by name. For example, ! 2381: ! 2382: @example ! 2383: C-h f auto-fill-mode @key{RET} ! 2384: @end example ! 2385: ! 2386: @noindent ! 2387: displays the documentation of @code{auto-fill-mode}. This is the only ! 2388: way to see the documentation of a command that is not bound to any key ! 2389: (one which you would normally call using @kbd{M-x}). ! 2390: ! 2391: @kbd{C-h f} is also useful for Lisp functions that you are planning to ! 2392: use in a Lisp program. For example, if you have just written the code ! 2393: @code{(make-vector len)} and want to be sure that you are using ! 2394: @code{make-vector} properly, type @kbd{C-h f make-vector @key{RET}}. Because ! 2395: @kbd{C-h f} allows all function names, not just command names, you may find ! 2396: that some of your favorite abbreviations that work in @kbd{M-x} don't work ! 2397: in @kbd{C-h f}. An abbreviation may be unique among command names yet fail ! 2398: to be unique when other function names are allowed. ! 2399: ! 2400: The function name for @kbd{C-h f} to describe has a default which is ! 2401: used if you type @key{RET} leaving the minibuffer empty. The default is ! 2402: the function called by the innermost Lisp expression in the buffer around ! 2403: point, @i{provided} that is a valid, defined Lisp function name. For ! 2404: example, if point is located following the text @samp{(make-vector (car ! 2405: x)}, the innermost list containing point is the one that starts with ! 2406: @samp{(make-vector}, so the default is to describe the function ! 2407: @code{make-vector}. ! 2408: ! 2409: @kbd{C-h f} is often useful just to verify that you have the right ! 2410: spelling for the function name. If @kbd{C-h f} mentions a default in the ! 2411: prompt, you have typed the name of a defined Lisp function. If that tells ! 2412: you what you want to know, just type @kbd{C-g} to cancel the @kbd{C-h f} ! 2413: command and go on editing. ! 2414: ! 2415: @kindex C-h w ! 2416: @findex where-is ! 2417: @kbd{C-h w @var{command} @key{RET}} tells you what keys are bound to ! 2418: @var{command}. It prints a list of the keys in the echo area. ! 2419: Alternatively, it says that the command is not on any keys, which implies ! 2420: that you must use @kbd{M-x} to call it.@refill ! 2421: ! 2422: @kindex C-h v ! 2423: @findex describe-variable ! 2424: @kbd{C-h v} (@code{describe-variable}) is like @kbd{C-h f} but describes ! 2425: Lisp variables instead of Lisp functions. Its default is the Lisp symbol ! 2426: around or before point, but only if that is the name of a known Lisp ! 2427: variable. @xref{Variables}.@refill ! 2428: ! 2429: @section Apropos ! 2430: ! 2431: @kindex C-h a ! 2432: @findex command-apropos ! 2433: @cindex apropos ! 2434: A more sophisticated sort of question to ask is, ``What are the commands ! 2435: for working with files?'' For this, type @kbd{C-h a file @key{RET}}, which ! 2436: displays a list of all command names that contain @samp{file}, such as ! 2437: @code{copy-file}, @code{find-file}, and so on. With each command name ! 2438: appears a brief description of how to use the command, and what keys you ! 2439: can currently invoke it with. For example, it would say that you can ! 2440: invoke @code{find-file} by typing @kbd{C-x C-f}. The @kbd{a} in @kbd{C-h ! 2441: a} stands for `Apropos'; @kbd{C-h a} runs the Lisp function ! 2442: @code{command-apropos}.@refill ! 2443: ! 2444: Because @kbd{C-h a} looks only for functions whose names contain the ! 2445: string which you specify, you must use ingenuity in choosing the string. ! 2446: If you are looking for commands for killing backwards and @kbd{C-h a ! 2447: kill-backwards @key{RET}} doesn't reveal any, don't give up. Try just ! 2448: @kbd{kill}, or just @kbd{backwards}, or just @kbd{back}. Be persistent. ! 2449: Pretend you are playing Adventure. Also note that you can use a ! 2450: regular expression as the argument (@pxref{Regexps}). ! 2451: ! 2452: Here is a set of arguments to give to @kbd{C-h a} that covers many ! 2453: classes of Emacs commands, since there are strong conventions for naming ! 2454: the standard Emacs commands. By giving you a feel for the naming ! 2455: conventions, this set should also serve to aid you in developing a ! 2456: technique for picking @code{apropos} strings. ! 2457: ! 2458: @quotation ! 2459: char, line, word, sentence, paragraph, region, page, sexp, list, defun, ! 2460: buffer, screen, window, file, dir, register, mode, ! 2461: beginning, end, forward, backward, next, previous, up, down, search, goto, ! 2462: kill, delete, mark, insert, yank, fill, indent, case, ! 2463: change, set, what, list, find, view, describe. ! 2464: @end quotation ! 2465: ! 2466: @findex apropos ! 2467: To list all Lisp symbols that contain a match for a regexp, not just ! 2468: the ones that are defined as commands, use the command @kbd{M-x apropos} ! 2469: instead of @kbd{C-h a}. ! 2470: ! 2471: @section Other Help Commands ! 2472: ! 2473: @kindex C-h i ! 2474: @findex info ! 2475: @kbd{C-h i} (@code{info}) runs the Info program, which is used for ! 2476: browsing through structured documentation files. The entire Emacs manual ! 2477: is available within Info. Eventually all the documentation of the GNU ! 2478: system will be available. Type @kbd{h} after entering Info to run ! 2479: a tutorial on using Info. ! 2480: ! 2481: @kindex C-h l ! 2482: @findex view-lossage ! 2483: If something surprising happens, and you are not sure what commands you ! 2484: typed, use @kbd{C-h l} (@code{view-lossage}). @kbd{C-h l} prints the last ! 2485: 100 command characters you typed in. If you see commands that you don't ! 2486: know, you can use @kbd{C-h c} to find out what they do. ! 2487: ! 2488: @kindex C-h m ! 2489: @findex describe-mode ! 2490: Emacs has several major modes, each of which redefines a few keys and ! 2491: makes a few other changes in how editing works. @kbd{C-h m} (@code{describe-mode}) ! 2492: prints documentation on the current major mode, which normally describes ! 2493: all the commands that are changed in this mode. ! 2494: ! 2495: @kindex C-h b ! 2496: @findex describe-bindings ! 2497: @kbd{C-h b} (@code{describe-bindings}) and @kbd{C-h s} ! 2498: (@code{describe-syntax}) present other information about the current ! 2499: Emacs mode. @kbd{C-h b} displays a list of all the key bindings now ! 2500: in effect; the local bindings of the current major mode first, ! 2501: followed by the global bindings (@pxref{Key Bindings}). @kbd{C-h s} ! 2502: displays the contents of the syntax table, with explanations of each ! 2503: character's syntax (@pxref{Syntax}).@refill ! 2504: ! 2505: @kindex C-h n ! 2506: @findex view-emacs-news ! 2507: @kindex C-h t ! 2508: @findex help-with-tutorial ! 2509: @kindex C-h C-c ! 2510: @findex describe-copying ! 2511: @kindex C-h C-d ! 2512: @findex describe-distribution ! 2513: @kindex C-h C-w ! 2514: @findex describe-no-warranty ! 2515: The other @kbd{C-h} options display various files of useful information. ! 2516: @kbd{C-h C-w} displays the full details on the complete absence of warranty ! 2517: for GNU Emacs. @kbd{C-h n} (@code{view-emacs-news}) displays the file ! 2518: @file{emacs/etc/NEWS}, which contains documentation on Emacs changes ! 2519: arranged chronologically. @kbd{C-h t} (@code{help-with-tutorial}) displays ! 2520: the learn-by-doing Emacs tutorial. @kbd{C-h C-c} (@code{describe-copying}) ! 2521: displays the file @file{emacs/etc/COPYING}, which tells you the conditions ! 2522: you must obey in distributing copies of Emacs. @kbd{C-h C-d} ! 2523: (@code{describe-distribution}) displays the file @file{emacs/etc/DISTRIB}, ! 2524: which tells you how you can order a copy of the latest version of ! 2525: Emacs.@refill ! 2526: ! 2527: @node Mark, Killing, Help, Top ! 2528: @chapter The Mark and the Region ! 2529: @cindex mark ! 2530: @cindex region ! 2531: ! 2532: There are many Emacs commands which operate on an arbitrary contiguous ! 2533: part of the current buffer. To specify the text for such a command to ! 2534: operate on, you set @dfn{the mark} at one end of it, and move point to the ! 2535: other end. The text between point and the mark is called @dfn{the region}. ! 2536: You can move point or the mark to adjust the boundaries of the region. It ! 2537: doesn't matter which one is set first chronologically, or which one comes ! 2538: earlier in the text. ! 2539: ! 2540: Once the mark has been set, it remains until it is set again at another ! 2541: place. The mark remains fixed with respect to the preceding character if ! 2542: text is inserted or deleted in the buffer. Each Emacs buffer has its own ! 2543: mark, so that when you return to a buffer that had been selected ! 2544: previously, it has the same mark it had before. ! 2545: ! 2546: Many commands that insert text, such as @kbd{C-y} (@code{yank}) and ! 2547: @kbd{M-x insert-buffer}, position the mark at one end of the inserted ! 2548: text---the opposite end from where point is positioned, so that the region ! 2549: contains the text just inserted. ! 2550: ! 2551: Aside from delimiting the region, the mark is also useful for remembering ! 2552: a spot that you may want to go back to. To make this feature more useful, ! 2553: Emacs remembers 16 previous locations of the mark, in the @code{mark ring}. ! 2554: ! 2555: @menu ! 2556: * Setting Mark:: Commands to set the mark. ! 2557: * Using Region:: Summary of ways to operate on contents of the region. ! 2558: * Marking Objects:: Commands to put region around textual units. ! 2559: * Mark Ring:: Previous mark positions saved so you can go back there. ! 2560: @end menu ! 2561: ! 2562: @node Setting Mark, Using Region, Mark, Mark ! 2563: @section Setting the Mark ! 2564: ! 2565: Here are some commands for setting the mark: ! 2566: ! 2567: @c WideCommands ! 2568: @table @kbd ! 2569: @item C-@key{SPC} ! 2570: Set the mark where point is (@code{set-mark-command}). ! 2571: @item C-@@ ! 2572: The same. ! 2573: @item C-x C-x ! 2574: Interchange mark and point (@code{exchange-point-and-mark}). ! 2575: @end table ! 2576: ! 2577: For example, if you wish to convert part of the buffer to all upper-case, ! 2578: you can use the @kbd{C-x C-u} (@code{upcase-region}) command, which operates ! 2579: on the text in the region. You can first go to the beginning of the text ! 2580: to be capitalized, type @kbd{C-@key{SPC}} to put the mark there, move to ! 2581: the end, and then type @kbd{C-x C-u}. Or, you can set the mark at the end ! 2582: of the text, move to the beginning, and then type @kbd{C-x C-u}. Most ! 2583: commands that operate on the text in the region have the word @code{region} ! 2584: in their names. ! 2585: ! 2586: @kindex C-SPC ! 2587: @findex set-mark-command ! 2588: The most common way to set the mark is with the @kbd{C-@key{SPC}} command ! 2589: (@code{set-mark-command}). This sets the mark where point is. Then you ! 2590: can move point away, leaving the mark behind. It is actually incorrect to ! 2591: speak of the character @kbd{C-@key{SPC}}; there is no such character. When ! 2592: you type @key{SPC} while holding down @key{CTRL}, what you get on most ! 2593: terminals is the character @kbd{C-@@}. This is the key actually bound to ! 2594: @code{set-mark-command}. But unless you are unlucky enough to have a ! 2595: terminal where typing @kbd{C-@key{SPC}} does not produce @kbd{C-@@}, you ! 2596: might as well think of this character as @kbd{C-@key{SPC}}. ! 2597: ! 2598: @kindex C-x C-x ! 2599: @findex exchange-point-and-mark ! 2600: Since terminals have only one cursor, there is no way for Emacs to show ! 2601: you where the mark is located. You have to remember. The usual solution ! 2602: to this problem is to set the mark and then use it soon, before you forget ! 2603: where it is. But you can see where the mark is with the command @kbd{C-x ! 2604: C-x} (@code{exchange-point-and-mark}) which puts the mark where point was and ! 2605: point where the mark was. The extent of the region is unchanged, but the ! 2606: cursor and point are now at the previous location of the mark. ! 2607: ! 2608: @kbd{C-x C-x} is also useful when you are satisfied with the location of ! 2609: point but want to move the mark; do @kbd{C-x C-x} to put point there and ! 2610: then you can move it. A second use of @kbd{C-x C-x}, if necessary, puts ! 2611: the mark at the new location with point back at its original location. ! 2612: ! 2613: @node Using Region, Marking Objects, Setting Mark, Mark ! 2614: @section Operating on the Region ! 2615: ! 2616: Once you have created an active region, you can do many things to ! 2617: the text in it: ! 2618: @itemize @bullet ! 2619: @item ! 2620: Kill it with @kbd{C-w} (@pxref{Killing}). ! 2621: @item ! 2622: Save it in a register with @kbd{C-x x} (@pxref{Registers}). ! 2623: @item ! 2624: Save it in a buffer or a file (@pxref{Accumulating Text}). ! 2625: @item ! 2626: Convert case with @kbd{C-x C-l} or @kbd{C-x C-u} @*(@pxref{Case}). ! 2627: @item ! 2628: Evaluate it as Lisp code with @kbd{M-x eval-region} (@pxref{Lisp Eval}). ! 2629: @item ! 2630: Fill it as text with @kbd{M-g} (@pxref{Filling}). ! 2631: @item ! 2632: Print hardcopy with @kbd{M-x print-region} (@pxref{Hardcopy}). ! 2633: @item ! 2634: Indent it with @kbd{C-x @key{TAB}} or @kbd{C-M-\} (@pxref{Indentation}). ! 2635: @end itemize ! 2636: ! 2637: @node Marking Objects, Mark Ring, Using Region, Mark ! 2638: @section Commands to Mark Textual Objects ! 2639: ! 2640: There are commands for placing point and the mark around a textual ! 2641: object such as a word, list, paragraph or page. ! 2642: ! 2643: @table @kbd ! 2644: @item M-@@ ! 2645: Set mark after end of next word (@code{mark-word}). This command and ! 2646: the following one do not move point. ! 2647: @item C-M-@@ ! 2648: Set mark after end of next Lisp expression (@code{mark-sexp}). ! 2649: @item M-h ! 2650: Put region around current paragraph (@code{mark-paragraph}). ! 2651: @item C-M-h ! 2652: Put region around current Lisp defun (@code{mark-defun}). ! 2653: @item C-x h ! 2654: Put region around entire buffer (@code{mark-whole-buffer}). ! 2655: @item C-x C-p ! 2656: Put region around current page (@code{mark-page}). ! 2657: @end table ! 2658: ! 2659: @kindex M-@@ ! 2660: @kindex C-M-@@ ! 2661: @findex mark-word ! 2662: @findex mark-sexp ! 2663: @kbd{M-@@} (@code{mark-word}) puts the mark at the end of the next word, ! 2664: while @kbd{C-M-@@} (@code{mark-sexp}) puts it at the end of the next Lisp ! 2665: expression. These characters allow you to save a little typing or ! 2666: redisplay, sometimes. ! 2667: ! 2668: @kindex M-h ! 2669: @kindex C-M-h ! 2670: @kindex C-x C-p ! 2671: @kindex C-x h ! 2672: @findex mark-paragraph ! 2673: @findex mark-defun ! 2674: @findex mark-page ! 2675: @findex mark-whole-buffer ! 2676: Other commands set both point and mark, to delimit an object in the ! 2677: buffer. @kbd{M-h} (@code{mark-paragraph}) moves point to the beginning of ! 2678: the paragraph that surrounds or follows point, and puts the mark at the end ! 2679: of that paragraph (@pxref{Paragraphs}). @kbd{M-h} does all that's ! 2680: necessary if you wish to indent, case-convert, or kill a whole paragraph. ! 2681: @kbd{C-M-h} (@code{mark-defun}) similarly puts point before and the mark ! 2682: after the current or following defun (@pxref{Defuns}). @kbd{C-x C-p} ! 2683: (@code{mark-page}) puts point before the current page (or the next or ! 2684: previous, according to the argument), and mark at the end (@pxref{Pages}). ! 2685: The mark goes after the terminating page delimiter (to include it), while ! 2686: point goes after the preceding page delimiter (to exclude it). Finally, ! 2687: @kbd{C-x h} (@code{mark-whole-buffer}) sets up the entire buffer as the ! 2688: region, by putting point at the beginning and the mark at the end. ! 2689: ! 2690: @node Mark Ring,, Marking Objects, Mark ! 2691: @section The Mark Ring ! 2692: ! 2693: @kindex C-u C-SPC ! 2694: @cindex mark ring ! 2695: @kindex C-u C-@@ ! 2696: Aside from delimiting the region, the mark is also useful for remembering ! 2697: a spot that you may want to go back to. To make this feature more useful, ! 2698: Emacs remembers 16 previous locations of the mark, in the @dfn{mark ring}. ! 2699: Most commands that set the mark push the old mark onto this ring. To ! 2700: return to a marked location, use @kbd{C-u C-@key{SPC}} (or @kbd{C-u C-@@}); this is ! 2701: the command @code{set-mark-command} given a numeric argument. It moves ! 2702: point to where the mark was, and restores the mark from the ring of former ! 2703: marks. So repeated use of this command moves point to all of the old marks ! 2704: on the ring, one by one. The marks you see go to the end of the ring, ! 2705: so no marks are lost. ! 2706: ! 2707: Each buffer has its own mark ring. All editing commands use the current ! 2708: buffer's mark ring. In particular, @kbd{C-u C-@key{SPC}} always stays in ! 2709: the same buffer. ! 2710: ! 2711: Many commands that can move long distances, such as @kbd{M-<} ! 2712: (@code{beginning-of-buffer}), start by setting the mark and saving the old ! 2713: mark on the mark ring. This is to make it easier for you to move back ! 2714: later. Searches do this except when they do not actually move point. You ! 2715: can tell when a command sets the mark because @samp{Mark Set} is printed in ! 2716: the echo area. ! 2717: ! 2718: @vindex mark-ring-max ! 2719: The variable @code{mark-ring-max} is the maximum number of entries to ! 2720: keep in the mark ring. If that many entries exist and another one is ! 2721: pushed, the last one in the list is discarded. Repeating @kbd{C-u ! 2722: C-@key{SPC}} circulates through the limited number of entries that are ! 2723: currently in the ring. ! 2724: ! 2725: @vindex mark-ring ! 2726: The variable @code{mark-ring} holds the mark ring itself, as a list of ! 2727: marker objects in the order most recent first. This variable is local ! 2728: in every buffer. ! 2729: ! 2730: @iftex ! 2731: @chapter Killing and Moving Text ! 2732: ! 2733: @dfn{Killing} means erasing text and copying it into the @dfn{kill ring}, ! 2734: from which it can be retrieved by @dfn{yanking} it. Some other systems ! 2735: that have recently become popular use the terms ``cutting'' and ``pasting'' ! 2736: for these operations. ! 2737: ! 2738: The commonest way of moving or copying text with Emacs is to kill it and ! 2739: later yank it in one or more places. This is very safe because all the ! 2740: text killed recently is remembered, and it is versatile, because the many ! 2741: commands for killing syntactic units can also be used for moving those ! 2742: units. There are also other ways of copying text for special purposes. ! 2743: ! 2744: Emacs has only one kill ring, so you can kill text in one buffer and yank ! 2745: it in another buffer. ! 2746: ! 2747: @end iftex ! 2748: ! 2749: @node Killing, Yanking, Mark, Top ! 2750: @section Deletion and Killing ! 2751: @findex delete-char ! 2752: @c ??? Should be backward-delete-char ! 2753: @findex delete-backward-char ! 2754: ! 2755: @cindex killing ! 2756: @cindex cutting ! 2757: @cindex deletion ! 2758: @kindex C-d ! 2759: @kindex DEL ! 2760: Most commands which erase text from the buffer save it so that you can ! 2761: get it back if you change your mind, or move or copy it to other parts of ! 2762: the buffer. These commands are known as @dfn{kill} commands. The rest of ! 2763: the commands that erase text do not save it; they are known as @dfn{delete} ! 2764: commands. (This distinction is made only for erasure of text in the ! 2765: buffer.) ! 2766: ! 2767: The delete commands include @kbd{C-d} (@code{delete-char}) and ! 2768: @key{DEL} (@code{delete-backward-char}), which delete only one character at ! 2769: a time, and those commands that delete only spaces or newlines. Commands ! 2770: that can destroy significant amounts of nontrivial data generally kill. ! 2771: The commands' names and individual descriptions use the words @samp{kill} ! 2772: and @samp{delete} to say which they do. If you do a kill or delete command ! 2773: by mistake, you can use the @kbd{C-x u} (@code{undo}) command to undo it ! 2774: (@pxref{Undo}).@refill ! 2775: ! 2776: @subsection Deletion ! 2777: ! 2778: @table @kbd ! 2779: @item C-d ! 2780: Delete next character (@code{delete-char}). ! 2781: @item @key{DEL} ! 2782: Delete previous character (@code{delete-backward-char}). ! 2783: @item M-\ ! 2784: Delete spaces and tabs around point (@code{delete-horizontal-space}). ! 2785: @item M-@key{SPC} ! 2786: Delete spaces and tabs around point, leaving one space ! 2787: (@code{just-one-space}). ! 2788: @item C-x C-o ! 2789: Delete blank lines around the current line (@code{delete-blank-lines}). ! 2790: @item M-^ ! 2791: Join two lines by deleting the intervening newline, and any indentation ! 2792: following it (@code{delete-indentation}). ! 2793: @end table ! 2794: ! 2795: The most basic delete commands are @kbd{C-d} (@code{delete-char}) and ! 2796: @key{DEL} (@code{delete-backward-char}). @kbd{C-d} deletes the character ! 2797: after point, the one the cursor is ``on top of''. Point doesn't move. ! 2798: @key{DEL} deletes the character before the cursor, and moves point back. ! 2799: Newlines can be deleted like any other characters in the buffer; deleting a ! 2800: newline joins two lines. Actually, @kbd{C-d} and @key{DEL} aren't always ! 2801: delete commands; if given an argument, they kill instead, since they can ! 2802: erase more than one character this way. ! 2803: ! 2804: @kindex M-\ ! 2805: @findex delete-horizontal-space ! 2806: @kindex M-SPC ! 2807: @findex just-one-space ! 2808: @kindex C-x C-o ! 2809: @findex delete-blank-lines ! 2810: @kindex M-^ ! 2811: @findex delete-indentation ! 2812: The other delete commands are those which delete only formatting ! 2813: characters: spaces, tabs and newlines. @kbd{M-\} (@code{delete-horizontal-space}) ! 2814: deletes all the spaces and tab characters before and after point. ! 2815: @kbd{M-@key{SPC}} (@code{just-one-space}) does likewise but leaves a single ! 2816: space after point, regardless of the number of spaces that existed ! 2817: previously (even zero). ! 2818: ! 2819: @kbd{C-x C-o} (@code{delete-blank-lines}) deletes all blank lines after ! 2820: the current line, and if the current line is blank deletes all blank lines ! 2821: preceding the current line as well (leaving one blank line, the current ! 2822: line). @kbd{M-^} (@code{delete-indentation}) joins the current line and ! 2823: the previous line, or the current line and the next line if given an ! 2824: argument, by deleting a newline and all surrounding spaces, possibly ! 2825: leaving a single space. @xref{Indentation,M-^}. ! 2826: ! 2827: @subsection Killing by Lines ! 2828: ! 2829: @table @kbd ! 2830: @item C-k ! 2831: Kill rest of line or one or more lines (@code{kill-line}). ! 2832: @end table ! 2833: ! 2834: @kindex C-k ! 2835: @findex kill-line ! 2836: The simplest kill command is @kbd{C-k}. If given at the beginning of a ! 2837: line, it kills all the text on the line, leaving it blank. If given on a ! 2838: blank line, the blank line disappears. As a consequence, if you go to the ! 2839: front of a non-blank line and type @kbd{C-k} twice, the line disappears ! 2840: completely. ! 2841: ! 2842: More generally, @kbd{C-k} kills from point up to the end of the line, ! 2843: unless it is at the end of a line. In that case it kills the newline ! 2844: following the line, thus merging the next line into the current one. ! 2845: Invisible spaces and tabs at the end of the line are ignored when deciding ! 2846: which case applies, so if point appears to be at the end of the line, you ! 2847: can be sure the newline will be killed. ! 2848: ! 2849: If @kbd{C-k} is given a positive argument, it kills that many lines and ! 2850: the newlines that follow them (however, text on the current line before ! 2851: point is spared). With a negative argument, it kills back to a number of ! 2852: line beginnings. An argument of @minus{}2 means kill back to the second line ! 2853: beginning. If point is at the beginning of a line, that line beginning ! 2854: doesn't count, so @kbd{C-u - 2 C-k} with point at the front of a line kills ! 2855: the two previous lines. ! 2856: ! 2857: @kbd{C-k} with an argument of zero kills all the text before point on the ! 2858: current line. ! 2859: ! 2860: @subsection Other Kill Commands ! 2861: @findex kill-line ! 2862: @findex kill-region ! 2863: @findex kill-word ! 2864: @findex backward-kill-word ! 2865: @findex kill-sexp ! 2866: @findex kill-sentence ! 2867: @findex backward-kill-sentence ! 2868: @kindex M-d ! 2869: @kindex M-DEL ! 2870: @kindex C-M-k ! 2871: @kindex C-x DEL ! 2872: @kindex M-k ! 2873: @kindex C-k ! 2874: @kindex C-w ! 2875: ! 2876: @c DoubleWideCommands ! 2877: @table @kbd ! 2878: @item C-w ! 2879: Kill region (from point to the mark) (@code{kill-region}). ! 2880: @xref{Words}. ! 2881: @item M-d ! 2882: Kill word (@code{kill-word}). ! 2883: @item M-@key{DEL} ! 2884: Kill word backwards (@code{backward-kill-word}). ! 2885: @item C-x @key{DEL} ! 2886: Kill back to beginning of sentence (@code{backward-kill-sentence}). ! 2887: @xref{Sentences}. ! 2888: @item M-k ! 2889: Kill to end of sentence (@code{kill-sentence}). ! 2890: @item C-M-k ! 2891: Kill sexp (@code{kill-sexp}). @xref{Lists}. ! 2892: @item M-z @var{char} ! 2893: Kill up to next occurrence of @var{char} (@code{zap-to-char}). ! 2894: @end table ! 2895: ! 2896: A kill command which is very general is @kbd{C-w} (@code{kill-region}), ! 2897: which kills everything between point and the mark. With this command, you ! 2898: can kill any contiguous sequence of characters, if you first set the mark ! 2899: at one end of them and go to the other end. ! 2900: ! 2901: @kindex M-z ! 2902: @findex zap-to-char ! 2903: A convenient way of killing is combined with searching: @kbd{M-z} ! 2904: (@code{zap-to-char}) reads a character and kills from point up to (but not ! 2905: including) the next occurrence of that character in the buffer. If there ! 2906: is no next occurrence, killing goes to the end of the buffer. A numeric ! 2907: argument acts as a repeat count. A negative argument means to search ! 2908: backward and kill text before point. ! 2909: ! 2910: Other syntactic units can be killed: words, with @kbd{M-@key{DEL}} and ! 2911: @kbd{M-d} (@pxref{Words}); sexps, with @kbd{C-M-k} (@pxref{Lists}); and ! 2912: sentences, with @kbd{C-x @key{DEL}} and @kbd{M-k} ! 2913: (@pxref{Sentences}).@refill ! 2914: ! 2915: @node Yanking, Accumulating Text, Killing, Top ! 2916: @section Yanking ! 2917: @cindex moving text ! 2918: @cindex copying text ! 2919: @cindex kill ring ! 2920: @cindex yanking ! 2921: @cindex pasting ! 2922: ! 2923: @dfn{Yanking} is getting back text which was killed. This is what some ! 2924: systems call ``pasting''. The usual way to move or copy text is to kill it ! 2925: and then yank it one or more times. ! 2926: ! 2927: @table @kbd ! 2928: @item C-y ! 2929: Yank last killed text (@code{yank}). ! 2930: @item M-y ! 2931: Replace re-inserted killed text with the previously killed text ! 2932: (@code{yank-pop}). ! 2933: @item M-w ! 2934: Save region as last killed text without actually killing it ! 2935: (@code{copy-region-as-kill}). ! 2936: @item C-M-w ! 2937: Append next kill to last batch of killed text (@code{append-next-kill}). ! 2938: @end table ! 2939: ! 2940: @menu ! 2941: * Kill Ring:: Where killed text is stored. Basic yanking. ! 2942: * Appending Kills:: Several kills in a row all yank together. ! 2943: * Earlier Kills:: Yanking something killed some time ago. ! 2944: @end menu ! 2945: ! 2946: @node Kill Ring, Appending Kills, Yanking, Yanking ! 2947: @subsection The Kill Ring ! 2948: ! 2949: @kindex C-y ! 2950: @findex Yank ! 2951: All killed text is recorded in the @dfn{kill ring}, a list of blocks of ! 2952: text that have been killed. There is only one kill ring, used in all ! 2953: buffers, so you can kill text in one buffer and yank it in another buffer. ! 2954: This is the usual way to move text from one file to another. ! 2955: (@xref{Accumulating Text}, for some other ways.) ! 2956: ! 2957: The command @kbd{C-y} (@code{yank}) reinserts the text of the most recent ! 2958: kill. It leaves the cursor at the end of the text. It sets the mark at ! 2959: the beginning of the text. @xref{Mark}. ! 2960: ! 2961: @kbd{C-u C-y} leaves the cursor in front of the text, and sets the mark ! 2962: after it. This is only if the argument is specified with just a @kbd{C-u}, ! 2963: precisely. Any other sort of argument, including @kbd{C-u} and digits, has ! 2964: an effect described below (under ``Yanking Earlier Kills''). ! 2965: ! 2966: @kindex M-w ! 2967: @findex copy-region-as-kill ! 2968: If you wish to copy a block of text, you might want to use @kbd{M-w} ! 2969: (@code{copy-region-as-kill}), which copies the region into the kill ring ! 2970: without removing it from the buffer. This is approximately equivalent to ! 2971: @kbd{C-w} followed by @kbd{C-y}, except that @kbd{M-w} does not mark the ! 2972: buffer as ``modified'' and does not temporarily change the screen. ! 2973: ! 2974: @node Appending Kills, Earlier Kills, Kill Ring, Yanking ! 2975: @subsection Appending Kills ! 2976: ! 2977: @cindex television ! 2978: Normally, each kill command pushes a new block onto the kill ring. ! 2979: However, two or more kill commands in a row combine their text into a ! 2980: single entry, so that a single @kbd{C-y} gets it all back as it was before ! 2981: it was killed. This means that you don't have to kill all the text in one ! 2982: command; you can keep killing line after line, or word after word, until ! 2983: you have killed it all, and you can still get it all back at once. (Thus ! 2984: we join television in leading people to kill thoughtlessly.) ! 2985: ! 2986: Commands that kill forward from point add onto the end of the previous ! 2987: killed text. Commands that kill backward from point add onto the ! 2988: beginning. This way, any sequence of mixed forward and backward kill ! 2989: commands puts all the killed text into one entry without rearrangement. ! 2990: Numeric arguments do not break the sequence of appending kills. For ! 2991: example, suppose the buffer contains ! 2992: ! 2993: @example ! 2994: This is the first ! 2995: line of sample text ! 2996: and here is the third. ! 2997: @end example ! 2998: ! 2999: @noindent ! 3000: with point at the beginning of the second line. If you type @kbd{C-k C-u 2 ! 3001: M-@key{DEL} C-k}, the first @kbd{C-k} kills the text @samp{line of sample ! 3002: text}, @kbd{C-u 2 M-@key{DEL}} kills @samp{the first} with the newline that ! 3003: followed it, and the second @kbd{C-k} kills the newline after the second ! 3004: line. The result is that the buffer contains @samp{This is and here is the ! 3005: third.} and a single kill entry contains @samp{the first@key{RET}line of ! 3006: sample text@key{RET}}---all the killed text, in its original order. ! 3007: ! 3008: @kindex C-M-w ! 3009: @findex append-next-kill ! 3010: If a kill command is separated from the last kill command by other ! 3011: commands (not just numeric arguments), it starts a new entry on the kill ! 3012: ring. But you can force it to append by first typing the command ! 3013: @kbd{C-M-w} (@code{append-next-kill}) in front of it. The @kbd{C-M-w} ! 3014: tells the following command, if it is a kill command, to append the text it ! 3015: kills to the last killed text, instead of starting a new entry. With ! 3016: @kbd{C-M-w}, you can kill several separated pieces of text and accumulate ! 3017: them to be yanked back in one place.@refill ! 3018: ! 3019: @node Earlier Kills,, Appending Kills, Yanking ! 3020: @subsection Yanking Earlier Kills ! 3021: ! 3022: @kindex M-y ! 3023: @findex yank-pop ! 3024: To recover killed text that is no longer the most recent kill, you need ! 3025: the @kbd{Meta-y} (@code{yank-pop}) command. @kbd{M-y} can be used only ! 3026: after a @kbd{C-y} or another @kbd{M-y}. It takes the text previously ! 3027: yanked and replaces it with the text from an earlier kill. So, to recover ! 3028: the text of the next-to-the-last kill, you first use @kbd{C-y} to recover ! 3029: the last kill, and then use @kbd{M-y} to replace it with the previous ! 3030: kill.@refill ! 3031: ! 3032: You can think in terms of a ``last yank'' pointer which points at an item ! 3033: in the kill ring. Each time you kill, the ``last yank'' pointer moves to ! 3034: the newly made item at the front of the ring. @kbd{C-y} yanks the item ! 3035: which the ``last yank'' pointer points to. @kbd{M-y} moves the ``last ! 3036: yank'' pointer to a different item, and the text in the buffer changes to ! 3037: match. Enough @kbd{M-y} commands can move the pointer to any item in the ! 3038: ring, so you can get any item into the buffer. Eventually the pointer ! 3039: reaches the end of the ring; the next @kbd{M-y} moves it to the first item ! 3040: again. ! 3041: ! 3042: Yanking moves the ``last yank'' pointer around the ring, but it does not ! 3043: change the order of the entries in the ring, which always runs from the ! 3044: most recent kill at the front to the oldest one still remembered. ! 3045: ! 3046: @kbd{M-y} can take a numeric argument, which tells it how many items to ! 3047: advance the ``last yank'' pointer by. A negative argument moves the ! 3048: pointer toward the front of the ring; from the front of the ring, it moves ! 3049: to the last entry and starts moving forward from there. ! 3050: ! 3051: Once the text you are looking for is brought into the buffer, you can ! 3052: stop doing @kbd{M-y} commands and it will stay there. It's just a copy of ! 3053: the kill ring item, so editing it in the buffer does not change what's in ! 3054: the ring. As long as no new killing is done, the ``last yank'' pointer ! 3055: remains at the same place in the kill ring, so repeating @kbd{C-y} will ! 3056: yank another copy of the same old kill. ! 3057: ! 3058: If you know how many @kbd{M-y} commands it would take to find the ! 3059: text you want, you can yank that text in one step using @kbd{C-y} with ! 3060: a numeric argument. @kbd{C-y} with an argument greater than one ! 3061: restores the text the specified number of entries back in the kill ! 3062: ring. Thus, @kbd{C-u 2 C-y} gets the next to the last block of killed ! 3063: text. It is equivalent to @kbd{C-y M-y}. @kbd{C-y} with a numeric ! 3064: argument starts counting from the ``last yank'' pointer, and sets the ! 3065: ``last yank'' pointer to the entry that it yanks. ! 3066: ! 3067: @vindex kill-ring-max ! 3068: The length of the kill ring is controlled by the variable ! 3069: @code{kill-ring-max}; no more than that many blocks of killed text are ! 3070: saved. ! 3071: ! 3072: @node Accumulating Text, Rectangles, Yanking, Top ! 3073: @section Accumulating Text ! 3074: @kindex C-x a ! 3075: @findex append-to-buffer ! 3076: @findex prepend-to-buffer ! 3077: @findex copy-to-buffer ! 3078: @findex append-to-file ! 3079: ! 3080: Usually we copy or move text by killing it and yanking it, but there are ! 3081: other ways that are useful for copying one block of text in many places, or ! 3082: for copying many scattered blocks of text into one place. ! 3083: ! 3084: You can accumulate blocks of text from scattered locations either into a ! 3085: buffer or into a file if you like. These commands are described here. You ! 3086: can also use Emacs registers for storing and accumulating text. ! 3087: @xref{Registers}. ! 3088: ! 3089: @table @kbd ! 3090: @item C-x a ! 3091: Append region to contents of specified buffer (@code{append-to-buffer}). ! 3092: @item M-x prepend-to-buffer ! 3093: Prepend region to contents of specified buffer. ! 3094: @item M-x copy-to-buffer ! 3095: Copy region into specified buffer, deleting that buffer's old contents. ! 3096: @item M-x insert-buffer ! 3097: Insert contents of specified buffer into current buffer at point. ! 3098: @item M-x append-to-file ! 3099: Append region to contents of specified file, at the end. ! 3100: @end table ! 3101: ! 3102: To accumulate text into a buffer, use the command @kbd{C-x a @var{buffername}} ! 3103: (@code{append-to-buffer}), which inserts a copy of the region into the ! 3104: buffer @var{buffername}, at the location of point in that buffer. If there ! 3105: is no buffer with that name, one is created. If you append text into a ! 3106: buffer which has been used for editing, the copied text goes into the ! 3107: middle of the text of the buffer, wherever point happens to be in it. ! 3108: ! 3109: Point in that buffer is left at the end of the copied text, so successive ! 3110: uses of @kbd{C-x a} accumulate the text in the specified buffer in the same ! 3111: order as they were copied. Strictly speaking, @kbd{C-x a} does not always ! 3112: append to the text already in the buffer; but if @kbd{C-x a} is the only ! 3113: command used to alter a buffer, it does always append to the existing text ! 3114: because point is always at the end. ! 3115: ! 3116: @kbd{M-x prepend-to-buffer} is just like @kbd{C-x a} except that point in ! 3117: the other buffer is left before the copied text, so successive prependings ! 3118: add text in reverse order. @kbd{M-x copy-to-buffer} is similar except that ! 3119: any existing text in the other buffer is deleted, so the buffer is left ! 3120: containing just the text newly copied into it. ! 3121: ! 3122: You can retrieve the accumulated text from that buffer with @kbd{M-x ! 3123: insert-buffer}; this too takes @var{buffername} as an argument. It inserts ! 3124: a copy of the text in buffer @var{buffername} into the selected buffer. ! 3125: You could alternatively select the other buffer for editing, perhaps moving ! 3126: text from it by killing or with @kbd{C-x a}. @xref{Buffers}, for ! 3127: background information on buffers. ! 3128: ! 3129: Instead of accumulating text within Emacs, in a buffer, you can append ! 3130: text directly into a file with @kbd{M-x append-to-file}, which takes ! 3131: @var{file-name} as an argument. It adds the text of the region to the end ! 3132: of the specified file. The file is changed immediately on disk. This ! 3133: command is normally used with files that are @i{not} being visited in ! 3134: Emacs. Using it on a file that Emacs is visiting can produce confusing ! 3135: results, because the text inside Emacs for that file will not change ! 3136: while the file itself changes. ! 3137: ! 3138: @node Rectangles, Registers, Accumulating Text, Top ! 3139: @section Rectangles ! 3140: @cindex rectangles ! 3141: ! 3142: The rectangle commands affect rectangular areas of the text: all the ! 3143: characters between a certain pair of columns, in a certain range of lines. ! 3144: Commands are provided to kill rectangles, yank killed rectangles, clear ! 3145: them out, or delete them. Rectangle commands are useful with text in ! 3146: multicolumnar formats, such as perhaps code with comments at the right, ! 3147: or for changing text into or out of such formats. ! 3148: ! 3149: When you must specify a rectangle for a command to work on, you do ! 3150: it by putting the mark at one corner and point at the opposite corner. ! 3151: The rectangle thus specified is called the @dfn{region-rectangle} ! 3152: because it is controlled about the same way the region is controlled. ! 3153: But remember that a given combination of point and mark values can be ! 3154: interpreted either as specifying a region or as specifying a ! 3155: rectangle; it is up to the command that uses them to choose the ! 3156: interpretation. ! 3157: ! 3158: @table @kbd ! 3159: @item M-x delete-rectangle ! 3160: Delete the text of the region-rectangle, moving any following text on ! 3161: each line leftward to the left edge of the region-rectangle. ! 3162: @item M-x kill-rectangle ! 3163: Similar, but also save the contents of the region-rectangle as the ! 3164: ``last killed rectangle''. ! 3165: @item M-x yank-rectangle ! 3166: Yank the last killed rectangle with its upper left corner at point. ! 3167: @item M-x open-rectangle ! 3168: Insert blank space to fill the space of the region-rectangle. ! 3169: The previous contents of the region-rectangle are pushed rightward. ! 3170: @item M-x clear-rectangle ! 3171: Clear the region-rectangle by replacing its contents with spaces. ! 3172: @end table ! 3173: ! 3174: The rectangle operations fall into two classes: commands deleting and ! 3175: moving rectangles, and commands for blank rectangles. ! 3176: ! 3177: @findex delete-rectangle ! 3178: @findex kill-rectangle ! 3179: There are two ways to get rid of the text in a rectangle: you can discard ! 3180: the text (delete it) or save it as the ``last killed'' rectangle. The ! 3181: commands for these two ways are @kbd{M-x delete-rectangle} and @kbd{M-x ! 3182: kill-rectangle}. In either case, the portion of each line that falls inside ! 3183: the rectangle's boundaries is deleted, causing following text (if any) on ! 3184: the line to move left. ! 3185: ! 3186: Note that ``killing'' a rectangle is not killing in the usual sense; the ! 3187: rectangle is not stored in the kill ring, but in a special place that ! 3188: can only record the most recent rectangle killed. This is because yanking ! 3189: a rectangle is so different from yanking linear text that different yank ! 3190: commands have to be used and yank-popping is hard to make sense of. ! 3191: ! 3192: Inserting a rectangle is the opposite of deleting one. All you need to ! 3193: specify is where to put the upper left corner; that is done by putting ! 3194: point there. The rectangle's first line is inserted there, the rectangle's ! 3195: second line is inserted at a point one line vertically down, and so on. ! 3196: The number of lines affected is determined by the height of the saved ! 3197: rectangle. ! 3198: ! 3199: @findex yank-rectangle ! 3200: To insert the last killed rectangle, type @kbd{M-x yank-rectangle}. ! 3201: This can be used to convert single-column lists into double-column ! 3202: lists; kill the second half of the list as a rectangle and then ! 3203: yank it beside the first line of the list. ! 3204: ! 3205: @findex open-rectangle ! 3206: @findex clear-rectangle ! 3207: There are two commands for working with blank rectangles: @kbd{M-x ! 3208: clear-rectangle} to blank out existing text, and @kbd{M-x open-rectangle} ! 3209: to insert a blank rectangle. Clearing a rectangle is equivalent to ! 3210: deleting it and then inserting as blank rectangle of the same size. ! 3211: ! 3212: Rectangles can also be copied into and out of registers. ! 3213: @xref{RegRect,,Rectangle Registers}. ! 3214: ! 3215: @node Registers, Display, Rectangles, Top ! 3216: @chapter Registers ! 3217: @cindex registers ! 3218: ! 3219: Emacs @dfn{registers} are places you can save text or positions for ! 3220: later use. Text saved in a register can be copied into the buffer ! 3221: once or many times; a position saved in a register is used by moving ! 3222: point to that position. Rectangles can also be copied into and out of ! 3223: registers (@pxref{Rectangles}). ! 3224: ! 3225: Each register has a name, which is a single character. A register can ! 3226: store either a piece of text or a position or a rectangle, but only one ! 3227: thing at any given time. Whatever you store in a register remains ! 3228: there until you store something else in that register. ! 3229: ! 3230: @menu ! 3231: * RegPos:: Saving positions in registers. ! 3232: * RegText:: Saving text in registers. ! 3233: * RegRect:: Saving rectangles in registers. ! 3234: @end menu ! 3235: ! 3236: @table @kbd ! 3237: @item M-x view-register @key{RET} @var{r} ! 3238: Display a description of what register @var{r} contains. ! 3239: @end table ! 3240: ! 3241: @findex view-register ! 3242: @kbd{M-x view-register} reads a register name as an argument and then ! 3243: displays the contents of the specified register. ! 3244: ! 3245: @node RegPos, RegText, Registers, Registers ! 3246: @section Saving Positions in Registers ! 3247: ! 3248: Saving a position records a spot in a buffer so that you can move ! 3249: back there later. Moving to a saved position reselects the buffer ! 3250: and moves point to the spot. ! 3251: ! 3252: @table @kbd ! 3253: @item C-x / @var{r} ! 3254: Save location of point in register @var{r} (@code{point-to-register}). ! 3255: @item C-x j @var{r} ! 3256: Jump to the location saved in register @var{r} (@code{register-to-point}). ! 3257: @end table ! 3258: ! 3259: @kindex C-x / ! 3260: @findex point-to-register ! 3261: To save the current location of point in a register, choose a name ! 3262: @var{r} and type @kbd{C-x / @var{r}}. The register @var{r} retains ! 3263: the location thus saved until you store something else in that ! 3264: register.@refill ! 3265: ! 3266: @kindex C-x j ! 3267: @findex register-to-point ! 3268: The command @kbd{C-x j @var{r}} moves point to the location recorded ! 3269: in register @var{r}. The register is not affected; it continues to ! 3270: record the same location. You can jump to the same position using the ! 3271: same register any number of times. ! 3272: ! 3273: @node RegText, RegRect, RegPos, Registers ! 3274: @section Saving Text in Registers ! 3275: ! 3276: When you want to insert a copy of the same piece of text frequently, it ! 3277: may be impractical to use the kill ring, since each subsequent kill moves ! 3278: the piece of text further down on the ring. It becomes hard to keep track ! 3279: of what argument is needed to retrieve the same text with @kbd{C-y}. An ! 3280: alternative is to store the text in a register with @kbd{C-x x} ! 3281: (@code{copy-to-register}) and then retrieve it with @kbd{C-x g} ! 3282: (@code{insert-register}). ! 3283: ! 3284: @table @kbd ! 3285: @item C-x x @var{r} ! 3286: Copy region into register @var{r} (@code{copy-to-register}). ! 3287: @item C-x g @var{r} ! 3288: Insert text contents of register @var{r} (@code{insert-register}). ! 3289: @end table ! 3290: ! 3291: @kindex C-x x ! 3292: @kindex C-x g ! 3293: @findex copy-to-register ! 3294: @findex insert-register ! 3295: @kbd{C-x x @var{r}} stores a copy of the text of the region into the ! 3296: register named @var{r}. Given a numeric argument, @kbd{C-x x} deletes the ! 3297: text from the buffer as well. ! 3298: ! 3299: @kbd{C-x g @var{r}} inserts in the buffer the text from register @var{r}. ! 3300: Normally it leaves point before the text and places the mark after, but ! 3301: with a numeric argument it puts point after the text and the mark before. ! 3302: ! 3303: @node RegRect,, RegText, Registers ! 3304: @section Saving Rectangles in Registers ! 3305: @cindex rectangle ! 3306: ! 3307: A register can contain a rectangle instead of linear text. The rectangle ! 3308: is represented as a list of strings. @xref{Rectangles}, for basic ! 3309: information on rectangles and how rectangles in the buffer are specified. ! 3310: ! 3311: @table @kbd ! 3312: @item C-x r @var{r} ! 3313: Copy the region-rectangle into register @var{r} @*(@code{copy-region-to-rectangle}). ! 3314: With numeric argument, delete it as well. ! 3315: @item C-x g @var{r} ! 3316: Insert the rectangle stored in register @var{r} (if it contains a ! 3317: rectangle) (@code{insert-register}). ! 3318: @end table ! 3319: ! 3320: The @kbd{C-x g} command inserts linear text if the register contains ! 3321: that, or inserts a rectangle if the register contains one. ! 3322: ! 3323: @node Display, Search, Registers, Top ! 3324: @chapter Controlling the Display ! 3325: ! 3326: Since only part of a large buffer fits in the window, Emacs tries to show ! 3327: the part that is likely to be interesting. The display control commands ! 3328: allow you to specify which part of the text you want to see. ! 3329: ! 3330: @table @kbd ! 3331: @item C-l ! 3332: Clear screen and redisplay, scrolling the selected window to center ! 3333: point vertically within it (@code{recenter}). ! 3334: @item C-v ! 3335: Scroll forward (a windowful or a specified number of lines) (@code{scroll-up}). ! 3336: @item M-v ! 3337: Scroll backward (@code{scroll-down}). ! 3338: @item @var{arg} C-l ! 3339: Scroll so point is on line @var{arg} (@code{recenter}). ! 3340: @item C-x < ! 3341: Scroll text in current window to the left (@code{scroll-left}). ! 3342: @item C-x > ! 3343: Scroll to the right (@code{scroll-right}). ! 3344: @item C-x $ ! 3345: Make deeply indented lines invisible (@code{set-selective-display}). ! 3346: @end table ! 3347: ! 3348: @menu ! 3349: * Scrolling:: Moving text up and down in a window. ! 3350: * Horizontal Scrolling:: Moving text left and right in a window. ! 3351: * Selective Display:: Hiding lines with lots of indentation. ! 3352: * Display Vars:: Information on variables for customizing display. ! 3353: @end menu ! 3354: ! 3355: @node Scrolling, Horizontal Scrolling, Display, Display ! 3356: @section Scrolling ! 3357: ! 3358: If a buffer contains text that is too large to fit entirely within a ! 3359: window that is displaying the buffer, Emacs shows a contiguous section of ! 3360: the text. The section shown always contains point. ! 3361: ! 3362: @cindex scrolling ! 3363: @dfn{Scrolling} means moving text up or down in the window so that ! 3364: different parts of the text are visible. Scrolling forward means that text ! 3365: moves up, and new text appears at the bottom. Scrolling backward moves ! 3366: text down and new text appears at the top. ! 3367: ! 3368: Scrolling happens automatically if you move point past the bottom or top ! 3369: of the window. You can also explicitly request scrolling with the commands ! 3370: in this section. ! 3371: ! 3372: @ifinfo ! 3373: @table @kbd ! 3374: @item C-l ! 3375: Clear screen and redisplay, scrolling the selected window to center ! 3376: point vertically within it (@code{recenter}). ! 3377: @item C-v ! 3378: Scroll forward (a windowful or a specified number of lines) (@code{scroll-up}). ! 3379: @item M-v ! 3380: Scroll backward (@code{scroll-down}). ! 3381: @item @var{arg} C-l ! 3382: Scroll so point is on line @var{arg} (@code{recenter}). ! 3383: @end table ! 3384: @end ifinfo ! 3385: ! 3386: @kindex C-l ! 3387: @findex recenter ! 3388: The most basic scrolling command is @kbd{C-l} (@code{recenter}) with no ! 3389: argument. It clears the entire screen and redisplays all windows. In ! 3390: addition, the selected window is scrolled so that point is halfway down ! 3391: from the top of the window. ! 3392: ! 3393: @kindex C-v ! 3394: @kindex M-v ! 3395: @findex scroll-up ! 3396: @findex scroll-down ! 3397: The scrolling commands @kbd{C-v} and @kbd{M-v} let you move all the text ! 3398: in the window up or down a few lines. @kbd{C-v} (@code{scroll-up}) with an ! 3399: argument shows you that many more lines at the bottom of the window, moving ! 3400: the text and point up together as @kbd{C-l} might. @kbd{C-v} with a ! 3401: negative argument shows you more lines at the top of the window. ! 3402: @kbd{Meta-v} (@code{scroll-down}) is like @kbd{C-v}, but moves in the ! 3403: opposite direction.@refill ! 3404: ! 3405: @vindex next-screen-context-lines ! 3406: To read the buffer a windowful at a time, use @kbd{C-v} with no argument. ! 3407: It takes the last two lines at the bottom of the window and puts them at ! 3408: the top, followed by nearly a whole windowful of lines not previously ! 3409: visible. If point was in the text scrolled off the top, it moves to the ! 3410: new top of the window. @kbd{M-v} with no argument moves backward with ! 3411: overlap similarly. The number of lines of overlap across a @kbd{C-v} or ! 3412: @kbd{M-v} is controlled by the variable @code{next-screen-context-lines}; by ! 3413: default, it is two. ! 3414: ! 3415: Another way to do scrolling is with @kbd{C-l} with a numeric argument. ! 3416: @kbd{C-l} does not clear the screen when given an argument; it only scrolls ! 3417: the selected window. With a positive argument @var{n}, it repositions text ! 3418: to put point @var{n} lines down from the top. An argument of zero puts ! 3419: point on the very top line. Point does not move with respect to the text; ! 3420: rather, the text and point move rigidly on the screen. @kbd{C-l} with a ! 3421: negative argument puts point that many lines from the bottom of the window. ! 3422: For example, @kbd{C-u - 1 C-l} puts point on the bottom line, and @kbd{C-u ! 3423: - 5 C-l} puts it five lines from the bottom. Just @kbd{C-u} as argument, ! 3424: as in @kbd{C-u C-l}, scrolls point to the center of the screen. ! 3425: ! 3426: @vindex scroll-step ! 3427: Scrolling happens automatically if point has moved out of the visible ! 3428: portion of the text when it is time to display. Usually the scrolling is ! 3429: done so as to put point vertically centered within the window. However, if ! 3430: the variable @code{scroll-step} has a nonzero value, an attempt is made to ! 3431: scroll the buffer by that many lines; if that is enough to bring point back ! 3432: into visibility, that is what is done. ! 3433: ! 3434: @node Horizontal Scrolling,, Scrolling, Display ! 3435: @section Horizontal Scrolling ! 3436: ! 3437: @ifinfo ! 3438: @table @kbd ! 3439: @item C-x < ! 3440: Scroll text in current window to the left (@code{scroll-left}). ! 3441: @item C-x > ! 3442: Scroll to the right (@code{scroll-right}). ! 3443: @end table ! 3444: @end ifinfo ! 3445: ! 3446: @kindex C-x < ! 3447: @kindex C-x > ! 3448: @findex scroll-left ! 3449: @findex scroll-right ! 3450: @cindex horizontal scrolling ! 3451: The text in a window can also be scrolled horizontally. This means that ! 3452: each line of text is shifted sideways in the window, and one or more ! 3453: characters at the beginning of each line are not displayed at all. When a ! 3454: window has been scrolled horizontally in this way, text lines are truncated ! 3455: rather than continued (@pxref{Continuation Lines}), with a @samp{$} appearing ! 3456: in the first column when there is text truncated to the left, and in the ! 3457: last column when there is text truncated to the right. ! 3458: ! 3459: The command @kbd{C-x <} (@code{scroll-left}) scrolls the selected window ! 3460: to the left by @var{n} columns with argument @var{n}. With no argument, it scrolls ! 3461: by almost the full width of the window (two columns less, to be precise). ! 3462: @kbd{C-x >} (@code{scroll-right}) scrolls similarly to the right. ! 3463: The window cannot be scrolled any farther to the right once it is ! 3464: displaying normally (with each line starting at the window's left margin); ! 3465: attempting to do so has no effect. ! 3466: ! 3467: @node Selective Display, Display Vars, Display, Display ! 3468: @section Selective Display ! 3469: @findex set-selective-display ! 3470: @kindex C-x $ ! 3471: ! 3472: Emacs has the ability to hide lines indented more than a certain number ! 3473: of columns (you specify how many columns). You can use this to get an ! 3474: overview of a part of a program. ! 3475: ! 3476: To hide lines, type @kbd{C-x $} (@code{set-selective-display}) with a ! 3477: numeric argument @var{n}. (@xref{Arguments}, for how to give the ! 3478: argument.) Then lines with at least @var{n} columns of indentation ! 3479: disappear from the screen. The only indication of their presence is that ! 3480: three dots (@samp{@dots{}}) appear at the end of each visible line that is ! 3481: followed by one or more invisible ones.@refill ! 3482: ! 3483: The invisible lines are still present in the buffer, and most editing ! 3484: commands see them as usual, so it is very easy to put point in the middle ! 3485: of invisible text. When this happens, the cursor appears at the end of the ! 3486: previous line, after the three dots. If point is at the end of the visible ! 3487: line, before the newline that ends it, the cursor appears before the three ! 3488: dots. ! 3489: ! 3490: The commands @kbd{C-n} and @kbd{C-p} move across the invisible lines as if they ! 3491: were not there. ! 3492: ! 3493: To make everything visible again, type @kbd{C-x $} with no argument. ! 3494: ! 3495: @node Display Vars,, Selective Display, Display ! 3496: @section Variables Controlling Display ! 3497: ! 3498: This section contains information for customization only. Beginning ! 3499: users should skip it. ! 3500: ! 3501: @vindex mode-line-inverse-video ! 3502: The variable @code{mode-line-inverse-video} controls whether the mode ! 3503: line is displayed in inverse video (assuming the terminal supports it); ! 3504: @code{nil} means don't do so. @xref{Mode Line}. ! 3505: ! 3506: @vindex inverse-video ! 3507: If the variable @code{inverse-video} is non-@code{nil}, Emacs attempts ! 3508: to invert all the lines of the display from what they normally are. ! 3509: ! 3510: @vindex visible-bell ! 3511: If the variable @code{visible-bell} is non-@code{nil}, Emacs attempts ! 3512: to make the whole screen blink when it would normally make an audible bell ! 3513: sound. This variable has no effect if your terminal does not have a way ! 3514: to make the screen blink.@refill ! 3515: ! 3516: @vindex no-redraw-on-reenter ! 3517: When you reenter Emacs after suspending, Emacs normally clears the screen ! 3518: and redraws the entire display. On some terminals with more than one page ! 3519: of memory, it is possible to arrange the termcap entry so that the ! 3520: @samp{ti} and @samp{te} strings (output to the terminal when Emacs is ! 3521: entered and exited, respectively) switch between pages of memory so as to ! 3522: use one page for Emacs and another page for other output. Then you might ! 3523: want to set the variable @code{no-redraw-on-reenter} non-@code{nil} so that ! 3524: Emacs will assume, when resumed, that the screen page it is using still ! 3525: contains what Emacs last wrote there. ! 3526: ! 3527: @vindex echo-keystrokes ! 3528: The variable @code{echo-keystrokes} controls the echoing of multi-character ! 3529: keys; its value is the number of seconds of pause required to cause echoing ! 3530: to start, or zero meaning don't echo at all. @xref{Echo Area}. ! 3531: ! 3532: @vindex ctl-arrow ! 3533: If the variable @code{ctl-arrow} is @code{nil}, control characters in the ! 3534: buffer are displayed with octal escape sequences, all except newline and ! 3535: tab. Altering the value of @code{ctl-arrow} makes it local to the current ! 3536: buffer; until that time, the default value is in effect. The default is ! 3537: initially @code{t}. @xref{Locals}. ! 3538: ! 3539: @vindex tab-width ! 3540: Normally, a tab character in the buffer is displayed as whitespace which ! 3541: extends to the next display tab stop position, and display tab stops come ! 3542: at intervals equal to eight spaces. The number of spaces per tab is ! 3543: controlled by the variable @code{tab-width}, which is made local by ! 3544: changing it, just like @code{ctl-arrow}. Note that how the tab character ! 3545: in the buffer is displayed has nothing to do with the definition of ! 3546: @key{TAB} as a command. ! 3547: ! 3548: @vindex selective-display-ellipses ! 3549: If you set the variable @code{selective-display-ellipses} to @code{nil}, ! 3550: the three dots do not appear at the end of a line that precedes invisible ! 3551: lines. Then there is no visible indication of the invisible lines. ! 3552: This variable too becomes local automatically when set. ! 3553: ! 3554: @node Search, Fixit, Display, Top ! 3555: @chapter Searching and Replacement ! 3556: @cindex searching ! 3557: ! 3558: Like other editors, Emacs has commands for searching for occurrences of ! 3559: a string. The principal search command is unusual in that it is ! 3560: @dfn{incremental}; it begins to search before you have finished typing the ! 3561: search string. There are also nonincremental search commands more like ! 3562: those of other editors. ! 3563: ! 3564: Besides the usual @code{replace-string} command that finds all ! 3565: occurrences of one string and replaces them with another, Emacs has a fancy ! 3566: replacement command called @code{query-replace} which asks interactively ! 3567: which occurrences to replace. ! 3568: ! 3569: @menu ! 3570: * Incremental Search:: Search happens as you type the string. ! 3571: * Nonincremental Search:: Specify entire string and then search. ! 3572: * Word Search:: Search for sequence of words. ! 3573: * Regexp Search:: Search for match for a regexp. ! 3574: * Regexps:: Syntax of regular expressions. ! 3575: * Search Case:: To ignore case while searching, or not. ! 3576: * Replace:: Search, and replace some or all matches. ! 3577: * Other Repeating Search:: Operating on all matches for some regexp. ! 3578: @end menu ! 3579: ! 3580: @node Incremental Search, Nonincremental Search, Search, Search ! 3581: @section Incremental Search ! 3582: ! 3583: An incremental search begins searching as soon as you type the first ! 3584: character of the search string. As you type in the search string, Emacs ! 3585: shows you where the string (as you have typed it so far) would be found. ! 3586: When you have typed enough characters to identify the place you want, you ! 3587: can stop. Depending on what you will do next, you may or may not need to ! 3588: terminate the search explicitly with an @key{ESC} first. ! 3589: ! 3590: @c WideCommands ! 3591: @table @kbd ! 3592: @item C-s ! 3593: Incremental search forward (@code{isearch-forward}). ! 3594: @item C-r ! 3595: Incremental search backward (@code{isearch-backward}). ! 3596: @end table ! 3597: ! 3598: @kindex C-s ! 3599: @kindex C-r ! 3600: @findex isearch-forward ! 3601: @findex isearch-backward ! 3602: @kbd{C-s} starts an incremental search. @kbd{C-s} reads characters from ! 3603: the keyboard and positions the cursor at the first occurrence of the ! 3604: characters that you have typed. If you type @kbd{C-s} and then @kbd{F}, ! 3605: the cursor moves right after the first @samp{F}. Type an @kbd{O}, and see ! 3606: the cursor move to after the first @samp{FO}. After another @kbd{O}, the ! 3607: cursor is after the first @samp{FOO} after the place where you started the ! 3608: search. Meanwhile, the search string @samp{FOO} has been echoed in the ! 3609: echo area.@refill ! 3610: ! 3611: The echo area display ends with three dots when actual searching is going ! 3612: on. When search is waiting for more input, the three dots are removed. ! 3613: (On slow terminals, the three dots are not displayed.) ! 3614: ! 3615: If you make a mistake in typing the search string, you can erase ! 3616: characters with @key{DEL}. Each @key{DEL} cancels the last character of ! 3617: search string. This does not happen until Emacs is ready to read another ! 3618: input character; first it must either find, or fail to find, the character ! 3619: you want to erase. If you do not want to wait for this to happen, use ! 3620: @kbd{C-g} as described below.@refill ! 3621: ! 3622: When you are satisfied with the place you have reached, you can type ! 3623: @key{ESC}, which stops searching, leaving the cursor where the search ! 3624: brought it. Also, any command not specially meaningful in searches stops ! 3625: the searching and is then executed. Thus, typing @kbd{C-a} would exit the ! 3626: search and then move to the beginning of the line. @key{ESC} is necessary ! 3627: only if the next command you want to type is a printing character, ! 3628: @key{DEL}, @key{ESC}, or another control character that is special within ! 3629: searches (@kbd{C-q}, @kbd{C-w}, @kbd{C-r}, @kbd{C-s} or @kbd{C-y}). ! 3630: ! 3631: Sometimes you search for @samp{FOO} and find it, but not the one you ! 3632: expected to find. There was a second @samp{FOO} that you forgot about, ! 3633: before the one you were looking for. In this event, type another @kbd{C-s} ! 3634: to move to the next occurrence of the search string. This can be done any ! 3635: number of times. If you overshoot, you can cancel some @kbd{C-s} ! 3636: characters with @key{DEL}. ! 3637: ! 3638: After you exit a search, you can search for the same string again by ! 3639: typing just @kbd{C-s C-s}: the first @kbd{C-s} is the key that invokes ! 3640: incremental search, and the second @kbd{C-s} means ``search again''. ! 3641: ! 3642: If your string is not found at all, the echo area says @samp{Failing ! 3643: I-Search}. The cursor is after the place where Emacs found as much of your ! 3644: string as it could. Thus, if you search for @samp{FOOT}, and there is no ! 3645: @samp{FOOT}, you might see the cursor after the @samp{FOO} in @samp{FOOL}. ! 3646: At this point there are several things you can do. If your string was ! 3647: mistyped, you can rub some of it out and correct it. If you like the place ! 3648: you have found, you can type @key{ESC} or some other Emacs command to ! 3649: ``accept what the search offered''. Or you can type @kbd{C-g}, which ! 3650: removes from the search string the characters that could not be found (the ! 3651: @samp{T} in @samp{FOOT}), leaving those that were found (the @samp{FOO} in ! 3652: @samp{FOOT}). A second @kbd{C-g} at that point cancels the search ! 3653: entirely, returning point to where it was when the search started. ! 3654: ! 3655: If a search is failing and you ask to repeat it by typing another ! 3656: @kbd{C-s}, it starts again from the beginning of the buffer. Repeating ! 3657: a failing reverse search with @kbd{C-r} starts again from the end. This ! 3658: is called @dfn{wrapping around}. @samp{Wrapped} appears in the search ! 3659: prompt once this has happened. ! 3660: ! 3661: @cindex quitting (in search) ! 3662: The @kbd{C-g} ``quit'' character does special things during searches; ! 3663: just what it does depends on the status of the search. If the search has ! 3664: found what you specified and is waiting for input, @kbd{C-g} cancels the ! 3665: entire search. The cursor moves back to where you started the search. If ! 3666: @kbd{C-g} is typed when there are characters in the search string that have ! 3667: not been found---because Emacs is still searching for them, or because it ! 3668: has failed to find them---then the search string characters which have not ! 3669: been found are discarded from the search string. With them gone, the ! 3670: search is now successful and waiting for more input, so a second @kbd{C-g} ! 3671: will cancel the entire search. ! 3672: ! 3673: To search for a control character such as @kbd{C-s} or @key{DEL} or @key{ESC}, ! 3674: you must quote it by typing @kbd{C-q} first. This function of @kbd{C-q} is ! 3675: analogous to its meaning as an Emacs command: it causes the following ! 3676: character to be treated the way a graphic character would normally be ! 3677: treated in the same context. ! 3678: ! 3679: You can change to searching backwards with @kbd{C-r}. If a search fails ! 3680: because the place you started was too late in the file, you should do this. ! 3681: Repeated @kbd{C-r} keeps looking for more occurrences backwards. A ! 3682: @kbd{C-s} starts going forwards again. @kbd{C-r} in a search can be cancelled ! 3683: with @key{DEL}. ! 3684: ! 3685: If you know initially that you want to search backwards, you can ! 3686: use @kbd{C-r} instead of @kbd{C-s} to start the search, because @kbd{C-r} ! 3687: is also a key running a command (@code{isearch-backward}) to search ! 3688: backward. ! 3689: ! 3690: The characters @kbd{C-y} and @kbd{C-w} can be used in incremental search ! 3691: to grab text from the buffer into the search string. This makes it ! 3692: convenient to search for another occurrence of text at point. @kbd{C-w} ! 3693: copies the word after point as part of the search string, advancing ! 3694: point over that word. Another @kbd{C-s} to repeat the search will then ! 3695: search for a string including that word. @kbd{C-y} is similar to @kbd{C-w} ! 3696: but copies all the rest of the current line into the search string. ! 3697: ! 3698: All the characters special in incremental search can be changed by setting ! 3699: the following variables: ! 3700: ! 3701: @vindex search-delete-char ! 3702: @vindex search-exit-char ! 3703: @vindex search-quote-char ! 3704: @vindex search-repeat-char ! 3705: @vindex search-reverse-char ! 3706: @vindex search-yank-line-char ! 3707: @vindex search-yank-word-char ! 3708: @table @code ! 3709: @item search-delete-char ! 3710: Character to delete from incremental search string (normally @key{DEL}). ! 3711: @item search-exit-char ! 3712: Character to exit incremental search (normally @key{ESC}). ! 3713: @item search-quote-char ! 3714: Character to quote special characters for incremental search (normally ! 3715: @kbd{C-q}). ! 3716: @item search-repeat-char ! 3717: Character to repeat incremental search forwards (normally @kbd{C-s}). ! 3718: @item search-reverse-char ! 3719: Character to repeat incremental search backwards (normally @kbd{C-r}). ! 3720: @item search-yank-line-char ! 3721: Character to pull rest of line from buffer into search string ! 3722: (normally @kbd{C-y}). ! 3723: @item search-yank-word-char ! 3724: Character to pull next word from buffer into search string (normally ! 3725: @kbd{C-w}). ! 3726: @end table ! 3727: ! 3728: @subsection Slow Terminal Incremental Search ! 3729: ! 3730: Incremental search on a slow terminal uses a modified style of display ! 3731: that is designed to take less time. Instead of redisplaying the buffer at ! 3732: each place the search gets to, it creates a new single-line window and uses ! 3733: that to display the line that the search has found. The single-line window ! 3734: comes into play as soon as point gets outside of the text that is already ! 3735: on the screen. ! 3736: ! 3737: When the search is terminated, the single-line window is removed. Only ! 3738: at this time is the window in which the search was done redisplayed to show ! 3739: its new value of point. ! 3740: ! 3741: The three dots at the end of the search string, normally used to indicate ! 3742: that searching is going on, are not displayed in slow style display. ! 3743: ! 3744: @vindex search-slow-speed ! 3745: The slow terminal style of display is used when the terminal baud rate is ! 3746: less than or equal to the value of the variable @code{search-slow-speed}, ! 3747: initially 1200. ! 3748: ! 3749: @vindex search-slow-window-lines ! 3750: The number of lines to use in slow terminal search display is controlled ! 3751: by the variable @code{search-slow-window-lines}. 1 is its normal value. ! 3752: ! 3753: @node Nonincremental Search, Word Search, Incremental Search, Search ! 3754: @section Nonincremental Search ! 3755: @cindex nonincremental search ! 3756: ! 3757: Emacs also has conventional nonincremental search commands, which require ! 3758: you to type the entire search string before searching begins. ! 3759: ! 3760: @table @kbd ! 3761: @item C-s @key{ESC} @var{string} @key{RET} ! 3762: Search for @var{string}. ! 3763: @item C-r @key{ESC} @var{string} @key{RET} ! 3764: Search backward for @var{string}. ! 3765: @end table ! 3766: ! 3767: To do a nonincremental search, first type @kbd{C-s @key{ESC}}. This ! 3768: enters the minibuffer to read the search string; terminate the string with ! 3769: @key{RET}, and then the search is done. If the string is not found the ! 3770: search command gets an error. ! 3771: ! 3772: The way @kbd{C-s @key{ESC}} works is that the @kbd{C-s} invokes ! 3773: incremental search, which is specially programmed to invoke nonincremental ! 3774: search if the argument you give it is empty. (Such an empty argument would ! 3775: otherwise be useless.) @kbd{C-r @key{ESC}} also works this way. ! 3776: ! 3777: @findex search-forward ! 3778: @findex search-backward ! 3779: Forward and backward nonincremental searches are implemented by the ! 3780: commands @code{search-forward} and @code{search-backward}. These commands ! 3781: may be bound to keys in the usual manner. The reason that incremental ! 3782: search is programmed to invoke them as well is that @kbd{C-s @key{ESC}} ! 3783: is the traditional sequence of characters used in Emacs to invoke ! 3784: nonincremental search. ! 3785: ! 3786: However, nonincremental searches performed using @kbd{C-s @key{ESC}} do ! 3787: not call @code{search-forward} right away. The first thing done is to see ! 3788: if the next character is @kbd{C-w}, which requests a word search. ! 3789: @ifinfo ! 3790: @xref{Word Search}. ! 3791: @end ifinfo ! 3792: ! 3793: @node Word Search, Regexp Search, Nonincremental Search, Search ! 3794: @section Word Search ! 3795: @cindex word search ! 3796: ! 3797: Word search searches for a sequence of words without regard to how the ! 3798: words are separated. More precisely, you type a string of many words, ! 3799: using single spaces to separate them, and the string can be found even if ! 3800: there are multiple spaces, newlines or other punctuation between the words. ! 3801: ! 3802: Word search is useful in editing documents formatted by text formatters. ! 3803: If you edit while looking at the printed, formatted version, you can't tell ! 3804: where the line breaks are in the source file. With word search, you can ! 3805: search without having to know them. ! 3806: ! 3807: @table @kbd ! 3808: @item C-s @key{ESC} C-w @var{words} @key{RET} ! 3809: Search for @var{words}, ignoring differences in punctuation. ! 3810: @item C-r @key{ESC} C-w @var{words} @key{RET} ! 3811: Search backward for @var{words}, ignoring differences in punctuation. ! 3812: @end table ! 3813: ! 3814: Word search is a special case of nonincremental search and is invoked ! 3815: with @kbd{C-s @key{ESC} C-w}. This is followed by the search string, which ! 3816: must always be terminated with @key{RET}. Being nonincremental, this ! 3817: search does not start until the argument is terminated. It works by ! 3818: constructing a regular expression and searching for that. @xref{Regexp ! 3819: Search}. ! 3820: ! 3821: A backward word search can be done by @kbd{C-r @key{ESC} C-w}. ! 3822: ! 3823: @findex word-search-forward ! 3824: @findex word-search-backward ! 3825: Forward and backward word searches are implemented by the commands ! 3826: @code{word-search-forward} and @code{word-search-backward}. These commands ! 3827: may be bound to keys in the usual manner. The reason that incremental ! 3828: search is programmed to invoke them as well is that @kbd{C-s @key{ESC} C-w} ! 3829: is the traditional Emacs sequence of keys for word search. ! 3830: ! 3831: @node Regexp Search, Regexps, Word Search, Search ! 3832: @section Regular Expression Search ! 3833: @cindex regular expression ! 3834: @cindex regexp ! 3835: ! 3836: A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern that ! 3837: denotes a set of strings, possibly an infinite set. Searching for matches ! 3838: for a regexp is a very powerful operation that editors on Unix systems have ! 3839: traditionally offered. In GNU Emacs, you can search for the next match for ! 3840: a regexp either incrementally or not. ! 3841: ! 3842: @kindex C-M-s ! 3843: @findex isearch-forward-regexp ! 3844: @findex isearch-backward-regexp ! 3845: Incremental search for a regexp is done by typing @kbd{C-M-s} ! 3846: (@code{isearch-forward-regexp}). This command reads a search string ! 3847: incrementally just like @kbd{C-s}, but it treats the search string as a ! 3848: regexp rather than looking for an exact match against the text in the ! 3849: buffer. Each time you add text to the search string, you make the regexp ! 3850: longer, and the new regexp is searched for. A reverse regexp search command ! 3851: @code{isearch-backward-regexp} also exists but no key runs it. ! 3852: ! 3853: All of the control characters that do special things within an ordinary ! 3854: incremental search have the same function in incremental regexp search. ! 3855: Typing @kbd{C-s} or @kbd{C-r} immediately after starting the search ! 3856: retrieves the last incremental search regexp used; that is to say, ! 3857: incremental regexp and non-regexp searches have independent defaults. ! 3858: ! 3859: Note that adding characters to the regexp in an incremental regexp search ! 3860: does not make the cursor move back and start again. Perhaps it ought to; I ! 3861: am not sure. As it stands, if you have searched for @samp{foo} and you ! 3862: add @samp{\|bar}, the search will not check for a @samp{bar} in the ! 3863: buffer before the @samp{foo}. ! 3864: ! 3865: @findex re-search-forward ! 3866: @findex re-search-backward ! 3867: Nonincremental search for a regexp is done by the functions ! 3868: @code{re-search-forward} and @code{re-search-backward}. You can invoke ! 3869: these with @kbd{M-x}, or bind them to keys. Also, you can call ! 3870: @code{re-search-forward} by way of incremental regexp search with ! 3871: @kbd{C-M-s @key{ESC}}. ! 3872: ! 3873: @node Regexps, Search Case, Regexp Search, Search ! 3874: @section Syntax of Regular Expressions ! 3875: ! 3876: Regular expressions have a syntax in which a few characters are special ! 3877: constructs and the rest are @dfn{ordinary}. An ordinary character is a ! 3878: simple regular expression which matches that character and nothing else. ! 3879: The special characters are @samp{$}, @samp{^}, @samp{.}, @samp{*}, ! 3880: @samp{+}, @samp{?}, @samp{[}, @samp{]} and @samp{\}; no new special ! 3881: characters will be defined. Any other character appearing in a regular ! 3882: expression is ordinary, unless a @samp{\} precedes it.@refill ! 3883: ! 3884: For example, @samp{f} is not a special character, so it is ordinary, and ! 3885: therefore @samp{f} is a regular expression that matches the string @samp{f} ! 3886: and no other string. (It does @i{not} match the string @samp{ff}.) Likewise, ! 3887: @samp{o} is a regular expression that matches only @samp{o}.@refill ! 3888: ! 3889: Any two regular expressions @var{a} and @var{b} can be concatenated. The ! 3890: result is a regular expression which matches a string if @var{a} matches ! 3891: some amount of the beginning of that string and @var{b} matches the rest of ! 3892: the string.@refill ! 3893: ! 3894: As a simple example, we can concatenate the regular expressions @samp{f} ! 3895: and @samp{o} to get the regular expression @samp{fo}, which matches only ! 3896: the string @samp{fo}. Still trivial. To do something nontrivial, you ! 3897: need to use one of the special characters. Here is a list of them. ! 3898: ! 3899: @table @kbd ! 3900: @item .@: @r{(Period)} ! 3901: is a special character that matches any single character except a newline. ! 3902: Using concatenation, we can make regular expressions like @samp{a.b} which ! 3903: matches any three-character string which begins with @samp{a} and ends with ! 3904: @samp{b}.@refill ! 3905: ! 3906: @item * ! 3907: is not a construct by itself; it is a suffix, which means the ! 3908: preceding regular expression is to be repeated as many times as ! 3909: possible. In @samp{fo*}, the @samp{*} applies to the @samp{o}, so ! 3910: @samp{fo*} matches one @samp{f} followed by any number of @samp{o}s. ! 3911: The case of zero @samp{o}s is allowed: @samp{fo*} does match ! 3912: @samp{f}.@refill ! 3913: ! 3914: @samp{*} always applies to the @i{smallest} possible preceding ! 3915: expression. Thus, @samp{fo*} has a repeating @samp{o}, not a ! 3916: repeating @samp{fo}.@refill ! 3917: ! 3918: The matcher processes a @samp{*} construct by matching, immediately, ! 3919: as many repetitions as can be found. Then it continues with the rest ! 3920: of the pattern. If that fails, backtracking occurs, discarding some ! 3921: of the matches of the @samp{*}-modified construct in case that makes ! 3922: it possible to match the rest of the pattern. For example, matching ! 3923: @samp{ca*ar} against the string @samp{caaar}, the @samp{a*} first ! 3924: tries to match all three @samp{a}s; but the rest of the pattern is ! 3925: @samp{ar} and there is only @samp{r} left to match, so this try fails. ! 3926: The next alternative is for @samp{a*} to match only two @samp{a}s. ! 3927: With this choice, the rest of the regexp matches successfully.@refill ! 3928: ! 3929: @item + ! 3930: Is a suffix character similar to @samp{*} except that it requires that ! 3931: the preceding expression be matched at least once. So, for example, ! 3932: @samp{ca+r} will match the strings @samp{car} and @samp{caaaar} ! 3933: but not the string @samp{cr}, whereas @samp{ca*r} would match all ! 3934: three strings.@refill ! 3935: ! 3936: @item ? ! 3937: Is a suffix character similar to @samp{*} except that it can match the ! 3938: preceding expression either once or not at all. For example, ! 3939: @samp{ca?r} will match @samp{car} or @samp{cr}; nothing else. ! 3940: ! 3941: @item [ @dots{} ] ! 3942: @samp{[} begins a @dfn{character set}, which is terminated by a ! 3943: @samp{]}. In the simplest case, the characters between the two form ! 3944: the set. Thus, @samp{[ad]} matches either one @samp{a} or one ! 3945: @samp{d}, and @samp{[ad]*} matches any string composed of just ! 3946: @samp{a}s and @samp{d}s (including the empty string), from which it ! 3947: follows that @samp{c[ad]*r} matches @samp{cr}, @samp{car}, @samp{cdr}, ! 3948: @samp{caddaar}, etc.@refill ! 3949: ! 3950: Character ranges can also be included in a character set, by writing ! 3951: two characters with a @samp{-} between them. Thus, @samp{[a-z]} ! 3952: matches any lower-case letter. Ranges may be intermixed freely with ! 3953: individual characters, as in @samp{[a-z$%.]}, which matches any lower ! 3954: case letter or @samp{$}, @samp{%} or period.@refill ! 3955: ! 3956: Note that the usual special characters are not special any more inside ! 3957: a character set. A completely different set of special characters ! 3958: exists inside character sets: @samp{]}, @samp{-} and @samp{^}.@refill ! 3959: ! 3960: To include a @samp{]} in a character set, you must make it the first ! 3961: character. For example, @samp{[]a]} matches @samp{]} or @samp{a}. To ! 3962: include a @samp{-}, write @samp{---}, which is a range containing only ! 3963: @samp{-}. To include @samp{^}, make it other than the first character ! 3964: in the set.@refill ! 3965: ! 3966: @item [^ @dots{} ] ! 3967: @samp{[^} begins a @dfn{complement character set}, which matches any ! 3968: character except the ones specified. Thus, @samp{[^a-z0-9A-Z]} ! 3969: matches all characters @i{except} letters and digits.@refill ! 3970: ! 3971: @samp{^} is not special in a character set unless it is the first ! 3972: character. The character following the @samp{^} is treated as if it ! 3973: were first (@samp{-} and @samp{]} are not special there). ! 3974: ! 3975: Note that a complement character set can match a newline, unless ! 3976: newline is mentioned as one of the characters not to match. ! 3977: ! 3978: @item ^ ! 3979: is a special character that matches the empty string, but only if at ! 3980: the beginning of a line in the text being matched. Otherwise it fails ! 3981: to match anything. Thus, @samp{^foo} matches a @samp{foo} which occurs ! 3982: at the beginning of a line. ! 3983: ! 3984: @item $ ! 3985: is similar to @samp{^} but matches only at the end of a line. Thus, ! 3986: @samp{xx*$} matches a string of one @samp{x} or more at the end of a line. ! 3987: ! 3988: @item \ ! 3989: has two functions: it quotes the special characters (including ! 3990: @samp{\}), and it introduces additional special constructs. ! 3991: ! 3992: Because @samp{\} quotes special characters, @samp{\$} is a regular ! 3993: expression which matches only @samp{$}, and @samp{\[} is a regular ! 3994: expression which matches only @samp{[}, and so on.@refill ! 3995: @end table ! 3996: ! 3997: Note: for historical compatibility, special characters are treated as ! 3998: ordinary ones if they are in contexts where their special meanings make no ! 3999: sense. For example, @samp{*foo} treats @samp{*} as ordinary since there is ! 4000: no preceding expression on which the @samp{*} can act. It is poor practice ! 4001: to depend on this behavior; better to quote the special character anyway, ! 4002: regardless of where is appears.@refill ! 4003: ! 4004: For the most part, @samp{\} followed by any character matches only ! 4005: that character. However, there are several exceptions: characters ! 4006: which, when preceded by @samp{\}, are special constructs. Such ! 4007: characters are always ordinary when encountered on their own. Here ! 4008: is a table of @samp{\} constructs. ! 4009: ! 4010: @table @kbd ! 4011: @item \| ! 4012: specifies an alternative. ! 4013: Two regular expressions @var{a} and @var{b} with @samp{\|} in ! 4014: between form an expression that matches anything that either @var{a} or ! 4015: @var{b} will match.@refill ! 4016: ! 4017: Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar} ! 4018: but no other string.@refill ! 4019: ! 4020: @samp{\|} applies to the largest possible surrounding expressions. Only a ! 4021: surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of ! 4022: @samp{\|}.@refill ! 4023: ! 4024: Full backtracking capability exists to handle multiple uses of @samp{\|}. ! 4025: ! 4026: @item \( @dots{} \) ! 4027: is a grouping construct that serves three purposes: ! 4028: ! 4029: @enumerate ! 4030: @item ! 4031: To enclose a set of @samp{\|} alternatives for other operations. ! 4032: Thus, @samp{\(foo\|bar\)x} matches either @samp{foox} or @samp{barx}. ! 4033: ! 4034: @item ! 4035: To enclose a complicated expression for the postfix @samp{*} to operate on. ! 4036: Thus, @samp{ba\(na\)*} matches @samp{bananana}, etc., with any (zero or ! 4037: more) number of @samp{na} strings.@refill ! 4038: ! 4039: @item ! 4040: To mark a matched substring for future reference. ! 4041: ! 4042: @end enumerate ! 4043: ! 4044: This last application is not a consequence of the idea of a ! 4045: parenthetical grouping; it is a separate feature which happens to be ! 4046: assigned as a second meaning to the same @samp{\( @dots{} \)} construct ! 4047: because there is no conflict in practice between the two meanings. ! 4048: Here is an explanation of this feature: ! 4049: ! 4050: @item \@var{digit} ! 4051: after the end of a @samp{\( @dots{} \)} construct, the matcher remembers the ! 4052: beginning and end of the text matched by that construct. Then, later on ! 4053: in the regular expression, you can use @samp{\} followed by @var{digit} ! 4054: to mean ``match the same text matched the @var{digit}'th time by the ! 4055: @samp{\( @dots{} \)} construct.''@refill ! 4056: ! 4057: The strings matching the first nine @samp{\( @dots{} \)} constructs appearing ! 4058: in a regular expression are assigned numbers 1 through 9 in order that the ! 4059: open-parentheses appear in the regular expression. @samp{\1} through ! 4060: @samp{\9} may be used to refer to the text matched by the corresponding ! 4061: @samp{\( @dots{} \)} construct. ! 4062: ! 4063: For example, @samp{\(.*\)\1} matches any newline-free string that is ! 4064: composed of two identical halves. The @samp{\(.*\)} matches the first ! 4065: half, which may be anything, but the @samp{\1} that follows must match ! 4066: the same exact text. ! 4067: ! 4068: @item \` ! 4069: matches the empty string, provided it is at the beginning ! 4070: of the buffer. ! 4071: ! 4072: @item \' ! 4073: matches the empty string, provided it is at the end of ! 4074: the buffer. ! 4075: ! 4076: @item \b ! 4077: matches the empty string, provided it is at the beginning or ! 4078: end of a word. Thus, @samp{\bfoo\b} matches any occurrence of ! 4079: @samp{foo} as a separate word. @samp{\bballs?\b} matches ! 4080: @samp{ball} or @samp{balls} as a separate word.@refill ! 4081: ! 4082: @item \B ! 4083: matches the empty string, provided it is @i{not} at the beginning or ! 4084: end of a word. ! 4085: ! 4086: @item \< ! 4087: matches the empty string, provided it is at the beginning of a word. ! 4088: ! 4089: @item \> ! 4090: matches the empty string, provided it is at the end of a word. ! 4091: ! 4092: @item \w ! 4093: matches any word-constituent character. The editor syntax table ! 4094: determines which characters these are. ! 4095: ! 4096: @item \W ! 4097: matches any character that is not a word-constituent. ! 4098: ! 4099: @item \s@var{code} ! 4100: matches any character whose syntax is @var{code}. @var{code} is a ! 4101: character which represents a syntax code: thus, @samp{w} for word ! 4102: constituent, @samp{-} for whitespace, @samp{(} for open-parenthesis, ! 4103: etc. @xref{Syntax}.@refill ! 4104: ! 4105: @item \S@var{code} ! 4106: matches any character whose syntax is not @var{code}. ! 4107: @end table ! 4108: ! 4109: Here is a complicated regexp, used by Emacs to recognize the end of a ! 4110: sentence together with any whitespace that follows. It is given in Lisp ! 4111: syntax to enable you to distinguish the spaces from the tab characters. In ! 4112: Lisp syntax, the string constant begins and ends with a double-quote. ! 4113: @samp{\"} stands for a double-quote as part of the regexp, @samp{\\} for a ! 4114: backslash as part of the regexp, @samp{\t} for a tab and @samp{\n} for a ! 4115: newline. ! 4116: ! 4117: @example ! 4118: "[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*" ! 4119: @end example ! 4120: ! 4121: @noindent ! 4122: This contains four parts in succession: a character set matching period, ! 4123: @samp{?} or @samp{!}; a character set matching close-brackets, ! 4124: quotes or parentheses, repeated any number of times; an alternative in ! 4125: backslash-parentheses that matches end-of-line, a tab or two spaces; and a ! 4126: character set matching whitespace characters, repeated any number of times. ! 4127: ! 4128: @node Search Case, Replace, Regexps, Search ! 4129: @section Searching and Case ! 4130: ! 4131: @vindex case-fold-search ! 4132: All sorts of searches in Emacs normally ignore the case of the text they ! 4133: are searching through; if you specify searching for @samp{FOO}, then ! 4134: @samp{Foo} and @samp{foo} are also considered a match. Regexps, and in ! 4135: particular character sets, are included: @samp{[aB]} would match @samp{a} ! 4136: or @samp{A} or @samp{b} or @samp{B}.@refill ! 4137: ! 4138: If you do not want this feature, set the variable @code{case-fold-search} ! 4139: to @code{nil}. Then all letters must match exactly, including case. This ! 4140: is a per-buffer variable; altering the variable affects only the current ! 4141: buffer, but there is a default value which you can change as well. ! 4142: @xref{Locals}. ! 4143: ! 4144: @node Replace, Other Repeating Search, Search Case, Search ! 4145: @section Replacement Commands ! 4146: @cindex replacement ! 4147: @cindex string substitution ! 4148: @cindex global substitution ! 4149: ! 4150: Global search-and-replace operations are not needed as often in Emacs as ! 4151: they are in other editors, but they are available. In addition to the ! 4152: simple @code{replace-string} command which is like that found in most ! 4153: editors, there is a @code{query-replace} command which asks you, for each ! 4154: occurrence of the pattern, whether to replace it. ! 4155: ! 4156: The replace commands all replace one string (or regexp) with one ! 4157: replacement string. It is possible to perform several replacements in ! 4158: parallel using the command @code{expand-region-abbrevs}. @xref{Expanding ! 4159: Abbrevs}. ! 4160: ! 4161: @menu ! 4162: * Unconditional Replace:: Replacing all matches for a string. ! 4163: * Regexp Replace:: Replacing all matches for a regexp. ! 4164: * Replacement and Case:: How replacements preserve case of letters. ! 4165: * Query Replace:: How to use querying. ! 4166: @end menu ! 4167: ! 4168: @node Unconditional Replace, Regexp Replace, Replace, Replace ! 4169: @subsection Unconditional Replacement ! 4170: @findex replace-string ! 4171: @findex replace-regexp ! 4172: ! 4173: @table @kbd ! 4174: @item M-x replace-string @key{RET} @var{string} @key{RET} @var{newstring} @key{RET} ! 4175: Replace every occurrence of @var{string} with @var{newstring}. ! 4176: @item M-x replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET} ! 4177: Replace every match for @var{regexp} with @var{newstring}. ! 4178: @end table ! 4179: ! 4180: To replace every instance of @samp{foo} after point with @samp{bar}, use ! 4181: the command @kbd{M-x replace-string} with the two arguments @samp{foo} and ! 4182: @samp{bar}. Replacement occurs only after point, so if you want to cover ! 4183: the whole buffer you must go to the beginning first. All occurrences up to ! 4184: the end of the buffer are replaced; to limit replacement to part of the ! 4185: buffer, narrow to that part of the buffer before doing the replacement ! 4186: (@pxref{Narrowing}). ! 4187: ! 4188: When @code{replace-string} exits, point is left at the last occurrence ! 4189: replaced. The value of point when the @code{replace-string} command was ! 4190: issued is remembered on the mark ring; @kbd{C-u C-@key{SPC}} moves back ! 4191: there. ! 4192: ! 4193: A numeric argument restricts replacement to matches that are surrounded ! 4194: by word boundaries. ! 4195: ! 4196: @node Regexp Replace, Replacement and Case, Unconditional Replace, Replace ! 4197: @subsection Regexp Replacement ! 4198: ! 4199: @code{replace-string} replaces exact matches for a single string. The ! 4200: similar command @code{replace-regexp} replaces any match for a specified ! 4201: pattern. ! 4202: ! 4203: In @code{replace-regexp}, the @var{newstring} need not be constant. It ! 4204: can refer to all or part of what is matched by the @var{regexp}. @samp{\&} ! 4205: in @var{newstring} stands for the entire text being replaced. ! 4206: @samp{\@var{d}} in @var{newstring}, where @var{d} is a digit, stands for ! 4207: whatever matched the @var{d}'th parenthesized grouping in @var{regexp}. ! 4208: For example,@refill ! 4209: ! 4210: @example ! 4211: M-x replace-regexp @key{RET} c[ad]+r @key{RET} \&-safe @key{RET} ! 4212: @end example ! 4213: ! 4214: @noindent ! 4215: would replace (for example) @samp{cadr} with @samp{cadr-safe} and @samp{cddr} ! 4216: with @samp{cddr-safe}. ! 4217: ! 4218: @example ! 4219: M-x replace-regexp @key{RET} \(c[ad]+r\)-safe @key{RET} \1 @key{RET} ! 4220: @end example ! 4221: ! 4222: @noindent ! 4223: would perform exactly the opposite replacements. To include a @samp{\} ! 4224: in the text to replace with, you must give @samp{\\}. ! 4225: ! 4226: @node Replacement and Case, Query Replace, Regexp Replace, Replace ! 4227: @subsection Replace Commands and Case ! 4228: ! 4229: @vindex case-replace ! 4230: @vindex case-fold-search ! 4231: If the arguments to a replace command are in lower case, it preserves ! 4232: case when it makes a replacement. Thus, the command ! 4233: ! 4234: @example ! 4235: M-x replace-string @key{RET} foo @key{RET} bar @key{RET} ! 4236: @end example ! 4237: ! 4238: @noindent ! 4239: replaces a lower case @samp{foo} with a lower case @samp{bar}, @samp{FOO} ! 4240: with @samp{BAR}, and @samp{Foo} with @samp{Bar}. If upper case letters are ! 4241: used in the second argument, they remain upper case every time that ! 4242: argument is inserted. If upper case letters are used in the first ! 4243: argument, the second argument is always substituted exactly as given, with ! 4244: no case conversion. Likewise, if the variable @code{case-replace} is set ! 4245: to @code{nil}, replacement is done without case conversion. If ! 4246: @code{case-fold-search} is set to @code{nil}, case is significant in ! 4247: matching occurrences of @samp{foo} to replace; also, case conversion of the ! 4248: replacement string is not done. ! 4249: ! 4250: @node Query Replace,, Replacement and Case, Replace ! 4251: @subsection Query Replace ! 4252: @cindex query replace ! 4253: ! 4254: @table @kbd ! 4255: @item M-% @var{string} @key{RET} @var{newstring} @key{RET} ! 4256: @itemx M-x query-replace @key{RET} @var{string} @key{RET} @var{newstring} @key{RET} ! 4257: Replace some occurrences of @var{string} with @var{newstring}. ! 4258: @item M-x query-replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET} ! 4259: Replace some matches for @var{regexp} with @var{newstring}. ! 4260: @end table ! 4261: ! 4262: @kindex M-% ! 4263: @findex query-replace ! 4264: If you want to change only some of the occurrences of @samp{foo} to ! 4265: @samp{bar}, not all of them, then you cannot use an ordinary ! 4266: @code{replace-string}. Instead, use @kbd{M-%} (@code{query-replace}). ! 4267: This command finds occurrences of @samp{foo} one by one, displays each ! 4268: occurrence and asks you whether to replace it. A numeric argument to ! 4269: @code{query-replace} tells it to consider only occurrences that are bounded ! 4270: by word-delimiter characters.@refill ! 4271: ! 4272: @findex query-replace-regexp ! 4273: Aside from querying, @code{query-replace} works just like ! 4274: @code{replace-string}, and @code{query-replace-regexp} works ! 4275: just like @code{replace-regexp}.@refill ! 4276: ! 4277: The things you can type when you are shown an occurrence of @var{string} ! 4278: or a match for @var{regexp} are: ! 4279: ! 4280: @kindex SPC (query-replace) ! 4281: @kindex DEL (query-replace) ! 4282: @kindex , (query-replace) ! 4283: @kindex ESC (query-replace) ! 4284: @kindex . (query-replace) ! 4285: @kindex ! (query-replace) ! 4286: @kindex ^ (query-replace) ! 4287: @kindex C-r (query-replace) ! 4288: @kindex C-w (query-replace) ! 4289: @kindex C-l (query-replace) ! 4290: ! 4291: @c WideCommands ! 4292: @table @kbd ! 4293: @item @key{SPC} ! 4294: to replace the occurrence with @var{newstring}. This preserves case, just ! 4295: like @code{replace-string}, provided @code{case-replace} is non-@code{nil}, ! 4296: as it normally is.@refill ! 4297: ! 4298: @item @key{DEL} ! 4299: to skip to the next occurrence without replacing this one. ! 4300: ! 4301: @item , @r{(Comma)} ! 4302: to replace this occurrence and display the result. You are then asked ! 4303: for another input character, except that since the replacement has ! 4304: already been made, @key{DEL} and @key{SPC} are equivalent. You could ! 4305: type @kbd{C-r} at this point (see below) to alter the replaced text. You ! 4306: could also type @kbd{C-x u} to undo the replacement; this exits the ! 4307: @code{query-replace}, so if you want to do further replacement you must use ! 4308: @kbd{C-x ESC} to restart (@pxref{Repetition}). ! 4309: ! 4310: @item @key{ESC} ! 4311: to exit without doing any more replacements. ! 4312: ! 4313: @item .@: @r{(Period)} ! 4314: to replace this occurrence and then exit. ! 4315: ! 4316: @item ! ! 4317: to replace all remaining occurrences without asking again. ! 4318: ! 4319: @item ^ ! 4320: to go back to the location of the previous occurrence (or what used to ! 4321: be an occurrence), in case you changed it by mistake. This works by ! 4322: popping the mark ring. Only one @kbd{^} in a row is allowed, because ! 4323: only one previous replacement location is kept during @code{query-replace}. ! 4324: ! 4325: @item C-r ! 4326: to enter a recursive editing level, in case the occurrence needs to be ! 4327: edited rather than just replaced with @var{newstring}. When you are ! 4328: done, exit the recursive editing level with @kbd{C-M-c} and the next ! 4329: occurrence will be displayed. @xref{Recursive Edit}. ! 4330: ! 4331: @item C-w ! 4332: to delete the occurrence, and then enter a recursive editing level as ! 4333: in @kbd{C-r}. Use the recursive edit to insert text to replace the ! 4334: deleted occurrence of @var{string}. When done, exit the recursive ! 4335: editing level with @kbd{C-M-c} and the next occurrence will be ! 4336: displayed. ! 4337: ! 4338: @item C-l ! 4339: to redisplay the screen and then give another answer. ! 4340: ! 4341: @item C-h ! 4342: to display a message summarizing these options, then give another ! 4343: answer. ! 4344: @end table ! 4345: ! 4346: If you type any other character, the @code{query-replace} is exited, and ! 4347: the character executed as a command. To restart the @code{query-replace}, ! 4348: use @kbd{C-x @key{ESC}}, which repeats the @code{query-replace} because it ! 4349: used the minibuffer to read its arguments. @xref{Repetition, C-x ESC}. ! 4350: ! 4351: @node Other Repeating Search,, Replace, Search ! 4352: @section Other Search-and-Loop Commands ! 4353: ! 4354: Here are some other commands that find matches for a regular expression. ! 4355: They all operate from point to the end of the buffer. ! 4356: ! 4357: @findex list-matching-lines ! 4358: @findex occur ! 4359: @findex count-matches ! 4360: @findex delete-non-matching-lines ! 4361: @findex delete-matching-lines ! 4362: @c grosscommands ! 4363: @table @kbd ! 4364: @item M-x occur ! 4365: Print each line that follows point and contains a match for the ! 4366: specified regexp. A numeric argument specifies the number of context ! 4367: lines to print before and after each matching line; the default is ! 4368: none. ! 4369: ! 4370: @kindex C-c C-c (Occur mode) ! 4371: The buffer @samp{*Occur*} containing the output serves as a menu for ! 4372: finding the occurrences in their original context. Find an occurrence ! 4373: as listed in @samp{*Occur*}, position point there and type @kbd{C-c ! 4374: C-c}; this switches to the buffer that was searched and moves point to ! 4375: the original of the same occurrence. ! 4376: ! 4377: @item M-x list-matching-lines ! 4378: Synonym for @kbd{M-x occur}. ! 4379: ! 4380: @item M-x count-matches ! 4381: Print the number of matches following point for the specified regexp. ! 4382: ! 4383: @item M-x delete-non-matching-lines ! 4384: Delete each line that follows point and does not contain a match for ! 4385: the specified regexp. ! 4386: ! 4387: @item M-x delete-matching-lines ! 4388: Delete each line that follows point and contains a match for the ! 4389: specified regexp. ! 4390: @end table ! 4391: ! 4392: @node Fixit, Files, Search, Top ! 4393: @chapter Commands for Fixing Typos ! 4394: @cindex typos ! 4395: @cindex mistakes, correcting ! 4396: ! 4397: In this chapter we describe the commands that are especially useful for ! 4398: the times when you catch a mistake in your text just after you have made ! 4399: it, or change your mind while composing text on line. ! 4400: ! 4401: @menu ! 4402: * Kill Errors:: Commands to kill a batch of recently entered text. ! 4403: * Transpose:: Exchanging two characters, words, lines, lists... ! 4404: * Fixing Case:: Correcting case of last word entered. ! 4405: * Spelling:: Apply spelling checker to a word, or a whole file. ! 4406: @end menu ! 4407: ! 4408: @node Kill Errors, Transpose, Fixit, Fixit ! 4409: @section Killing Your Mistakes ! 4410: ! 4411: @table @kbd ! 4412: @item @key{DEL} ! 4413: Delete last character (@code{delete-backward-char}). ! 4414: @item M-@key{DEL} ! 4415: Kill last word (@code{backward-kill-word}). ! 4416: @item C-x @key{DEL} ! 4417: Kill to beginning of sentence (@code{backward-kill-sentence}). ! 4418: @end table ! 4419: ! 4420: @kindex DEL ! 4421: @findex delete-backward-char ! 4422: The @key{DEL} character (@code{delete-backward-char}) is the most ! 4423: important correction command. When used among graphic (self-inserting) ! 4424: characters, it can be thought of as canceling the last character typed. ! 4425: ! 4426: @kindex M-DEL ! 4427: @kindex C-x DEL ! 4428: @findex backward-kill-word ! 4429: @findex backward-kill-sentence ! 4430: When your mistake is longer than a couple of characters, it might be more ! 4431: convenient to use @kbd{M-@key{DEL}} or @kbd{C-x @key{DEL}}. ! 4432: @kbd{M-@key{DEL}} kills back to the start of the last word, and @kbd{C-x ! 4433: @key{DEL}} kills back to the start of the last sentence. @kbd{C-x ! 4434: @key{DEL}} is particularly useful when you are thinking of what to write as ! 4435: you type it, in case you change your mind about phrasing. ! 4436: @kbd{M-@key{DEL}} and @kbd{C-x @key{DEL}} save the killed text for ! 4437: @kbd{C-y} and @kbd{M-y} to retrieve. @xref{Yanking}.@refill ! 4438: ! 4439: @kbd{M-@key{DEL}} is often useful even when you have typed only a few ! 4440: characters wrong, if you know you are confused in your typing and aren't ! 4441: sure exactly what you typed. At such a time, you cannot correct with ! 4442: @key{DEL} except by looking at the screen to see what you did. It requires ! 4443: less thought to kill the whole word and start over again. ! 4444: ! 4445: @node Transpose, Fixing Case, Kill Errors, Fixit ! 4446: @section Transposing Text ! 4447: ! 4448: @table @kbd ! 4449: @item C-t ! 4450: Transpose two characters (@code{transpose-chars}). ! 4451: @item M-t ! 4452: Transpose two words (@code{transpose-words}). ! 4453: @item C-M-t ! 4454: Transpose two balanced expressions (@code{transpose-sexps}). ! 4455: @item C-x C-t ! 4456: Transpose two lines (@code{transpose-lines}). ! 4457: @end table ! 4458: ! 4459: @cindex transposition ! 4460: @kindex C-t ! 4461: @findex transpose-chars ! 4462: The common error of transposing two characters can be fixed, when they ! 4463: are adjacent, with the @kbd{C-t} command (@code{transpose-chars}). Normally, ! 4464: @kbd{C-t} transposes the two characters on either side of point. When ! 4465: given at the end of a line, rather than transposing the last character of ! 4466: the line with the newline, which would be useless, @kbd{C-t} transposes the ! 4467: last two characters on the line. So, if you catch your transposition error ! 4468: right away, you can fix it with just a @kbd{C-t}. If you don't catch it so ! 4469: fast, you must move the cursor back to between the two transposed ! 4470: characters. If you transposed a space with the last character of the word ! 4471: before it, the word motion commands are a good way of getting there. ! 4472: Otherwise, a reverse search (@kbd{C-r}) is often the best way. ! 4473: @xref{Search}. ! 4474: ! 4475: ! 4476: @kindex C-x C-t ! 4477: @findex transpose-lines ! 4478: @kindex M-t ! 4479: @findex transpose-words ! 4480: @kindex C-M-t ! 4481: @findex transpose-sexps ! 4482: @kbd{Meta-t} (@code{transpose-words}) transposes the word before point ! 4483: with the word after point. It moves point forward over a word, dragging ! 4484: the word preceding or containing point forward as well. The punctuation ! 4485: characters between the words do not move. For example, @w{@samp{FOO, BAR}} ! 4486: transposes into @w{@samp{BAR, FOO}} rather than @samp{@w{BAR FOO,}}. ! 4487: ! 4488: @kbd{C-M-t} (@code{transpose-sexps}) is a similar command for transposing ! 4489: two expressions (@pxref{Lists}), and @kbd{C-x C-t} (@code{transpose-lines}) ! 4490: exchanges lines. They work like @kbd{M-t} except in determining the ! 4491: division of the text into syntactic units. ! 4492: ! 4493: A numeric argument to a transpose command serves as a repeat count: it ! 4494: tells the transpose command to move the character (word, sexp, line) before ! 4495: or containing point across several other characters (words, sexps, lines). ! 4496: For example, @kbd{C-u 3 C-t} moves the character before point forward ! 4497: across three other characters. This is equivalent to repeating @kbd{C-t} ! 4498: three times. @kbd{C-u - 4 M-t} moves the word before point backward across ! 4499: four words. @kbd{C-u - C-M-t} would cancel the effect of plain ! 4500: @kbd{C-M-t}.@refill ! 4501: ! 4502: A numeric argument of zero is assigned a special meaning (because ! 4503: otherwise a command with a repeat count of zero would do nothing): to ! 4504: transpose the character (word, sexp, line) ending after point with the ! 4505: one ending after the mark. ! 4506: ! 4507: @node Fixing Case, Spelling, Transpose, Fixit ! 4508: @section Case Conversion ! 4509: ! 4510: @table @kbd ! 4511: @item M-- M-l ! 4512: Convert last word to lower case. Note @kbd{Meta--} is Meta-minus. ! 4513: @item M-- M-u ! 4514: Convert last word to all upper case. ! 4515: @item M-- M-c ! 4516: Convert last word to lower case with capital initial. ! 4517: @end table ! 4518: ! 4519: @findex downcase-word ! 4520: @findex upcase-word ! 4521: @findex capitalize-word ! 4522: @kindex M-@t{-} M-l ! 4523: @kindex M-@t{-} M-u ! 4524: @kindex M-@t{-} M-c ! 4525: @cindex case conversion ! 4526: @cindex words ! 4527: A very common error is to type words in the wrong case. Because of this, ! 4528: the word case-conversion commands @kbd{M-l}, @kbd{M-u} and @kbd{M-c} have a ! 4529: special feature when used with a negative argument: they do not move the ! 4530: cursor. As soon as you see you have mistyped the last word, you can simply ! 4531: case-convert it and go on typing. @xref{Case}.@refill ! 4532: ! 4533: @node Spelling,, Fixing Case, Fixit ! 4534: @section Checking and Correcting Spelling ! 4535: @cindex spelling ! 4536: ! 4537: @c doublewidecommands ! 4538: @table @kbd ! 4539: @item M-$ ! 4540: Check and correct spelling of word (@code{spell-word}). ! 4541: @item M-x spell-buffer ! 4542: Check and correct spelling of each word in the buffer. ! 4543: @item M-x spell-region ! 4544: Check and correct spelling of each word in the region. ! 4545: @item M-x spell-string ! 4546: Check spelling of specified word. ! 4547: @end table ! 4548: ! 4549: @kindex M-$ ! 4550: @findex spell-word ! 4551: To check the spelling of the word before point, and optionally correct it ! 4552: as well, use the command @kbd{M-$} (@code{spell-word}). This command runs ! 4553: an inferior process containing the @code{spell} program to see whether the ! 4554: word is correct English. If it is not, it asks you to edit the word (in ! 4555: the minibuffer) into a corrected spelling, and then does a @code{query-replace} ! 4556: to substitute the corrected spelling for the old one throughout the buffer. ! 4557: ! 4558: If you exit the minibuffer without altering the original spelling, it ! 4559: means you do not want to do anything to that word. Then the @code{query-replace} ! 4560: is not done. ! 4561: ! 4562: @findex spell-buffer ! 4563: @kbd{M-x spell-buffer} checks each word in the buffer the same way that ! 4564: @code{spell-word} does, doing a @code{query-replace} if appropriate for ! 4565: every incorrect word.@refill ! 4566: ! 4567: @findex spell-region ! 4568: @kbd{M-x spell-region} is similar but operates only on the region, not ! 4569: the entire buffer. ! 4570: ! 4571: @findex spell-string ! 4572: @kbd{M-x spell-string} reads a string as an argument and checks whether ! 4573: that is a correctly spelled English word. It prints in the echo area a ! 4574: message giving the answer. ! 4575: ! 4576: @node Files, Buffers, Fixit, Top ! 4577: @chapter File Handling ! 4578: @cindex files ! 4579: ! 4580: The basic unit of stored data in Unix is the @dfn{file}. To edit a file, ! 4581: you must tell Emacs to examine the file and prepare a buffer containing a ! 4582: copy of the file's text. This is called @dfn{visiting} the file. Editing ! 4583: commands apply directly to text in the buffer; that is, to the copy inside ! 4584: Emacs. Your changes appear in the file itself only when you @dfn{save} the ! 4585: buffer back into the file. ! 4586: ! 4587: In addition to visiting and saving files, Emacs can delete, copy, rename, ! 4588: and append to files, and operate on file directories. ! 4589: ! 4590: @menu ! 4591: * File Names:: How to type and edit file name arguments. ! 4592: * Visiting:: Visiting a file prepares Emacs to edit the file. ! 4593: * Saving:: Saving makes your changes permanent. ! 4594: * Reverting:: Reverting cancels all the changes not saved. ! 4595: * Auto Save:: Auto Save periodically protects against loss of data. ! 4596: * ListDir:: Listing the contents of a file directory. ! 4597: * Dired:: ``Editing'' a directory to delete, rename, etc. ! 4598: the files in it. ! 4599: * Misc File Ops:: Other things you can do on files. ! 4600: @end menu ! 4601: ! 4602: @node File Names, Visiting, Files, Files ! 4603: @section File Names ! 4604: @cindex file names ! 4605: ! 4606: Most Emacs commands that operate on a file require you to specify the ! 4607: file name. (Saving and reverting are exceptions; the buffer knows which ! 4608: file name to use for them.) File names are specified using the minibuffer ! 4609: (@pxref{Minibuffer}). @dfn{Completion} is available, to make it easier to ! 4610: specify long file names. @xref{Completion}. ! 4611: ! 4612: There is always a @dfn{default file name} which will be used if you type ! 4613: just @key{RET}, entering an empty argument. Normally the default file name ! 4614: is the name of the file visited in the current buffer; this makes it easy ! 4615: to operate on that file with any of the Emacs file commands. ! 4616: ! 4617: @vindex default-directory ! 4618: Each buffer has a default directory, normally the same as the directory ! 4619: of the file visited in that buffer. When Emacs reads a file name, if you ! 4620: do not specify a directory, the default directory is used. If you specify ! 4621: a directory in a relative fashion, with a name that does not start with a ! 4622: slash, it is interpreted with respect to the default directory. The ! 4623: default directory is kept in the variable @code{default-directory}, which ! 4624: has a separate value in every buffer. ! 4625: ! 4626: For example, if the default file name is @file{/u/rms/gnu/gnu.tasks} then ! 4627: the default directory is @file{/u/rms/gnu/}. If you type just @samp{foo}, ! 4628: which does not specify a directory, it is short for @file{/u/rms/gnu/foo}. ! 4629: @samp{../.login} would stand for @file{/u/rms/.login}. @samp{new/foo} ! 4630: would stand for the filename @file{/u/rms/gnu/new/foo}. ! 4631: ! 4632: The command @kbd{M-x pwd} prints the current buffer's default directory, ! 4633: and the command @kbd{M-x cd} sets it (to a value read using the ! 4634: minibuffer). A buffer's default directory changes only when the @code{cd} ! 4635: command is used. A file-visiting buffer's default directory is initialized ! 4636: to the directory of the file that is visited there. If a buffer is made ! 4637: randomly with @kbd{C-x b}, its default directory is copied from that of the ! 4638: buffer that was current at the time. ! 4639: ! 4640: @vindex insert-default-directory ! 4641: The default directory actually appears in the minibuffer when the ! 4642: minibuffer becomes active to read a file name. This serves two purposes: ! 4643: it shows you what the default is, so that you can type a relative file name ! 4644: and know with certainty what it will mean, and it allows you to edit the ! 4645: default to specify a different directory. This insertion of the default ! 4646: directory is inhibited if the variable @code{insert-default-directory} is ! 4647: set to @code{nil}. ! 4648: ! 4649: Note that it is legitimate to type an absolute file name after you enter ! 4650: the minibuffer, ignoring the presence of the default directory name as part ! 4651: of the text. The final minibuffer contents may look invalid, but that is ! 4652: not so. @xref{Minibuffer File}. ! 4653: ! 4654: @samp{$} in a file name is used to substitute environment variables. For ! 4655: example, if you have used the shell command @samp{setenv FOO rms/hacks} to ! 4656: set up an environment variable named @samp{FOO}, then you can use ! 4657: @file{/u/$FOO/test.c} or @file{/u/$@{FOO@}/test.c} as an abbreviation for ! 4658: @file{/u/rms/hacks/test.c}. The environment variable name consists of all ! 4659: the alphanumeric characters after the @samp{$}; alternatively, it may be ! 4660: enclosed in braces after the @samp{$}. Note that the @samp{setenv} command ! 4661: affects Emacs only if done before Emacs is started. ! 4662: ! 4663: To access a file with @samp{$} in its name, type @samp{$$}. This pair ! 4664: is converted to a single @samp{$} at the same time as variable substitution ! 4665: is performed for single @samp{$}. The Lisp function that performs the ! 4666: substitution is called @code{substitute-in-file-name}. The substitution ! 4667: is performed only on filenames read as such using the minibuffer. ! 4668: ! 4669: @node Visiting, Saving, File Names, Files ! 4670: @section Visiting Files ! 4671: @cindex visiting files ! 4672: ! 4673: @c WideCommands ! 4674: @table @kbd ! 4675: @item C-x C-f ! 4676: Visit a file (@code{find-file}). ! 4677: @item C-x C-v ! 4678: Visit a different file instead of the one visited last ! 4679: (@code{find-alternate-file}). ! 4680: @item C-x 4 C-f ! 4681: Visit a file, in another window (@code{find-file-other-window}). Don't ! 4682: change this window. ! 4683: @end table ! 4684: ! 4685: @cindex files ! 4686: @cindex visiting ! 4687: @cindex saving ! 4688: @dfn{Visiting} a file means copying its contents into Emacs where you can ! 4689: edit them. Emacs makes a new buffer for each file that you visit. We say ! 4690: that the buffer is visiting the file that it was created to hold. Emacs ! 4691: constructs the buffer name from the file name by throwing away the ! 4692: directory, keeping just the name proper. For example, a file named ! 4693: @file{/usr/rms/emacs.tex} would get a buffer named @samp{emacs.tex}. If ! 4694: there is already a buffer with that name, a unique name is constructed by ! 4695: appending @samp{<2>}, @samp{<3>}, or so on, using the lowest number that ! 4696: makes a name that is not already in use. ! 4697: ! 4698: Each window's mode line shows the name of the buffer that is being displayed ! 4699: in that window, so you can always tell what buffer you are editing. ! 4700: ! 4701: The changes you make with Emacs are made in the Emacs buffer. They do ! 4702: not take effect in the file that you visited, or any place permanent, until ! 4703: you @dfn{save} the buffer. Saving the buffer means that Emacs writes the ! 4704: current contents of the buffer into its visited file. @xref{Saving}. ! 4705: ! 4706: @cindex modified (buffer) ! 4707: If a buffer contains changes that have not been saved, the buffer is said ! 4708: to be @dfn{modified}. This is important because it implies that some ! 4709: changes will be lost if the buffer is not saved. The mode line displays ! 4710: two stars near the left margin if the buffer is modified. ! 4711: ! 4712: @kindex C-x C-f ! 4713: @findex find-file ! 4714: To visit a file, use the command @kbd{C-x C-f} (@code{find-file}). Follow ! 4715: the command with the name of the file you wish to visit, terminated by a ! 4716: @key{RET}. ! 4717: ! 4718: The file name is read using the minibuffer (@pxref{Minibuffer}), with ! 4719: defaulting and completion in the standard manner (@pxref{File Names}). ! 4720: While in the minibuffer, you can abort @kbd{C-x C-f} by typing @kbd{C-g}. ! 4721: ! 4722: Your confirmation that @kbd{C-x C-f} has completed successfully is the ! 4723: appearance of new text on the screen and a new buffer name in the mode ! 4724: line. If the specified file does not exist and could not be created, or ! 4725: cannot be read, then an error results. The error message is printed in the ! 4726: echo area, and includes the file name which Emacs was trying to visit. ! 4727: ! 4728: If you visit a file that is already in Emacs, @kbd{C-x C-f} does not make ! 4729: another copy. It selects the existing buffer containing that file. ! 4730: However, before doing so, it checks that the file itself has not changed ! 4731: since you visited or saved it last. If the file has changed, a warning ! 4732: message is printed. @xref{Interlocking,,Simultaneous Editing}. ! 4733: ! 4734: @cindex creating files ! 4735: What if you want to create a file? Just visit it. Emacs prints ! 4736: @samp{(New File)} in the echo area, but in other respects behaves as if you ! 4737: had visited an existing empty file. If you make any changes and save them, ! 4738: the file is created. ! 4739: ! 4740: @kindex C-x C-v ! 4741: @findex find-alternate-file ! 4742: If you visit a nonexistent file unintentionally (because you typed the ! 4743: wrong file name), use the @kbd{C-x C-v} (@code{find-alternate-file}) ! 4744: command to visit the file you wanted. @kbd{C-x C-v} is similar to @kbd{C-x ! 4745: C-f}, but it kills the current buffer (after first offering to save it if ! 4746: it is modified). @kbd{C-x C-v} is allowed even if the current buffer ! 4747: is not visiting a file. ! 4748: ! 4749: @vindex find-file-run-dired ! 4750: If the file you specify is actually a directory, Dired is called on that ! 4751: directory (@pxref{Dired}). This can be inhibited by setting the variable ! 4752: @code{find-file-run-dired} to @code{nil}; then it is an error to try to ! 4753: visit a directory. ! 4754: ! 4755: @kindex C-x 4 f ! 4756: @findex find-file-other-window ! 4757: @kbd{C-x 4 f} (@code{find-file-other-window}) is like @kbd{C-x C-f} ! 4758: except that the buffer containing the specified file is selected in another ! 4759: window. The window that was selected before @kbd{C-x 4 f} continues to ! 4760: show the same buffer it was already showing. If this command is used when ! 4761: only one window is being displayed, that window is split in two, with one ! 4762: window showing the same before as before, and the other one showing the ! 4763: newly requested file. @xref{Windows}. ! 4764: ! 4765: @vindex find-file-hooks ! 4766: @vindex find-file-not-found-hooks ! 4767: There are two hook variables that allow extensions to modify the ! 4768: operation of visiting files. Visiting a file that does not exist runs the ! 4769: functions in the list @code{find-file-not-found-hooks}; the value of this ! 4770: variable is expected to be a list of functions, and the functions are ! 4771: called one by one until one of them returns non-@code{nil}. Any visiting ! 4772: of a file, whether extant or not, expects @code{find-file-hooks} to ! 4773: contain list of functions and calls them all, one by one. In both cases ! 4774: the functions receive no arguments. Visiting a nonexistent file ! 4775: runs the @code{find-file-not-found-hooks} first. ! 4776: ! 4777: @node Saving, Reverting, Visiting, Files ! 4778: @section Saving Files ! 4779: ! 4780: @dfn{Saving} a buffer in Emacs means writing its contents back into the file ! 4781: that was visited in the buffer. ! 4782: ! 4783: @table @kbd ! 4784: @item C-x C-s ! 4785: Save the current buffer in its visited file (@code{save-buffer}). ! 4786: @item C-x s ! 4787: Save any or all buffers in their visited files (@code{save-some-buffers}). ! 4788: @item M-~ ! 4789: Forget that the current buffer has been changed (@code{not-modified}). ! 4790: @item C-x C-w ! 4791: Save the current buffer in a specified file, and record that file as ! 4792: the one visited in the buffer (@code{write-file}). ! 4793: @item M-x set-visited-file-name ! 4794: Change file the name under which the current buffer will be saved. ! 4795: @end table ! 4796: ! 4797: @kindex C-x C-s ! 4798: @findex save-buffer ! 4799: When you wish to save the file and make your changes permanent, type ! 4800: @kbd{C-x C-s} (@code{save-buffer}). After saving is finished, @kbd{C-x C-s} ! 4801: prints a message such as ! 4802: ! 4803: @example ! 4804: Wrote /u/rms/gnu/gnu.tasks ! 4805: @end example ! 4806: ! 4807: @noindent ! 4808: If the selected buffer is not modified (no changes have been made in it ! 4809: since the buffer was created or last saved), saving is not really done, ! 4810: because it would have no effect. Instead, @kbd{C-x C-s} prints a message ! 4811: in the echo area saying ! 4812: ! 4813: @example ! 4814: (No changes need to be written) ! 4815: @end example ! 4816: ! 4817: @kindex C-x s ! 4818: @findex save-some-buffers ! 4819: The command @kbd{C-x s} (@code{save-some-buffers}) can save any or all modified ! 4820: buffers. First it asks, for each modified buffer, whether to save it. ! 4821: These questions should be answered with @kbd{y} or @kbd{n}. @kbd{C-x C-c}, ! 4822: the key that kills Emacs, invokes @code{save-some-buffers} and therefore ! 4823: asks the same questions. ! 4824: ! 4825: @kindex M-~ ! 4826: @findex not-modified ! 4827: If you have changed a buffer and do not want the changes to be saved, you ! 4828: should take some action to prevent it. Otherwise, each time you use ! 4829: @code{save-some-buffers} you are liable to save it by mistake. One thing ! 4830: you can do is type @kbd{M-~} (@code{not-modified}), which clears out the ! 4831: indication that the buffer is modified. If you do this, none of the save ! 4832: commands will believe that the buffer needs to be saved. (@samp{~} is often ! 4833: used as a mathematical symbol for `not'; thus @kbd{Meta-~} is `not', metafied.) ! 4834: You could also use @code{set-visited-file-name} (see below) to mark the ! 4835: buffer as visiting a different file name, one which is not in use for ! 4836: anything important. Alternatively, you can undo all the changes made since ! 4837: the file was visited or saved, by reading the text from the file again. ! 4838: This is called @dfn{reverting}. @xref{Reverting}. You could also undo all ! 4839: the changes by repeating the undo command @kbd{C-x u} until you have undone ! 4840: all the changes; but this only works if you have not made more changes than ! 4841: the undo mechanism can remember. ! 4842: ! 4843: @findex set-visited-file-name ! 4844: @kbd{M-x set-visited-file-name} alters the name of the file that the ! 4845: current buffer is visiting. It reads the new file name using the ! 4846: minibuffer. It can be used on a buffer that is not visiting a file, too. ! 4847: The buffer's name is changed to correspond to the file it is now visiting ! 4848: in the usual fashion (unless the new name is in use already for some other ! 4849: buffer; in that case, the buffer name is not changed). ! 4850: @code{set-visited-file-name} does not save the buffer in the newly visited ! 4851: file; it just alters the records inside Emacs so that, if you save the ! 4852: buffer, it will be saved in that file. It also marks the buffer as ! 4853: ``modified'' so that @kbd{C-x C-s} @i{will} save. ! 4854: ! 4855: @kindex C-x C-w ! 4856: @findex write-file ! 4857: If you wish to mark the buffer as visiting a different file and save it ! 4858: right away, use @kbd{C-x C-w} (@code{write-file}). It is precisely ! 4859: equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s}. ! 4860: @kbd{C-x C-s} used on a buffer that is not visiting with a file has the ! 4861: same effect as @kbd{C-x C-w}; that is, it reads a file name, marks the ! 4862: buffer as visiting that file, and saves it there. The default file name in ! 4863: a buffer that is not visiting a file is made by combining the buffer name ! 4864: with the buffer's default directory. ! 4865: ! 4866: If Emacs is about to save a file and sees that the date of the latest ! 4867: version on disk does not match what Emacs last read or wrote, Emacs ! 4868: notifies you of this fact, because it probably indicates a problem caused ! 4869: by simultaneous editing and requires your immediate attention. ! 4870: @xref{Interlocking,, Simultaneous Editing}. ! 4871: ! 4872: @vindex require-final-newline ! 4873: If the variable @code{require-final-newline} is non-@code{nil}, Emacs ! 4874: puts a newline at the end of any file that doesn't already end in one, ! 4875: every time a file is saved or written. ! 4876: ! 4877: @vindex write-file-hooks ! 4878: You can implement other ways to write files, and other things to be done ! 4879: before writing them, using the hook variable @code{write-file-hooks}. The ! 4880: value of this variable should be a list of Lisp functions. When a file is ! 4881: to be written, the functions in the list are called, one by one, with no ! 4882: arguments. If one of them returns a non-@code{nil} value, Emacs takes this ! 4883: to mean that the file has been written in some suitable fashion; the rest ! 4884: of the functions are not called, and normal writing is not done. ! 4885: ! 4886: @menu ! 4887: * Backup:: How Emacs saves the old version of your file. ! 4888: * Interlocking:: How Emacs protects against simultaneous editing ! 4889: of one file by two users. ! 4890: @end menu ! 4891: ! 4892: @node Backup, Interlocking, Saving, Saving ! 4893: @subsection Backup Files ! 4894: @cindex backup file ! 4895: @vindex make-backup-files ! 4896: ! 4897: Because Unix does not provide version numbers in file names, rewriting a ! 4898: file in Unix automatically destroys all record of what the file used to ! 4899: contain. Thus, saving a file from Emacs throws away the old contents of ! 4900: the file---or it would, except that Emacs carefully copies the old contents ! 4901: to another file, called the @dfn{backup} file, before actually saving. ! 4902: (Provided the variable @code{make-backup-files} is non-@code{nil}. ! 4903: Backup files are not written if this variable is @code{nil}). ! 4904: ! 4905: At your option, Emacs can keep either a single backup file or a series of ! 4906: numbered backup files for each file that you edit. ! 4907: ! 4908: Emacs makes a backup for a file only the first time the file is saved ! 4909: from one buffer. No matter how many times you save a file, its backup file ! 4910: continues to contain the contents from before the file was visited. ! 4911: Normally this means that the backup file contains the contents from before ! 4912: the current editing session; however, if you kill the buffer and then visit ! 4913: the file again, a new backup file will be made by the next save. ! 4914: ! 4915: @menu ! 4916: * Names: Backup Names. How backup files are named; ! 4917: Choosing single or numbered backup files. ! 4918: * Deletion: Backup Deletion. Emacs deletes excess numbered backups. ! 4919: * Copying: Backup Copying. Backups can be made by copying or renaming. ! 4920: @end menu ! 4921: ! 4922: @node Backup Names, Backup Deletion, Backup, Backup ! 4923: @subsubsection Single or Numbered Backups ! 4924: ! 4925: If you choose to have a single backup file (this is the default), ! 4926: the backup file's name is constructed by appending @samp{~} to the ! 4927: file name being edited; thus, the backup file for @file{eval.c} would ! 4928: be @file{eval.c~}. ! 4929: ! 4930: If you choose to have a series of numbered backup files, backup file ! 4931: names are made by appending @samp{.~}, the number, and another @samp{~} to ! 4932: the original file name. Thus, the backup files of @file{eval.c} would be ! 4933: called @file{eval.c.~1~}, @file{eval.c.~2~}, and so on, through names ! 4934: like @file{eval.c.~259~} and beyond. ! 4935: ! 4936: If protection stops you from writing backup files under the usual names, ! 4937: the backup file is written as @file{%backup%~} in your home directory. ! 4938: Only one such file can exist, so only the most recently made such backup is ! 4939: available. ! 4940: ! 4941: @vindex version-control ! 4942: The choice of single backup or numbered backups is controlled by the ! 4943: variable @code{version-control}. Its possible values are ! 4944: ! 4945: @table @code ! 4946: @item t ! 4947: Make numbered backups. ! 4948: @item nil ! 4949: Make numbered backups for files that have numbered backups already. ! 4950: Otherwise, make single backups. ! 4951: @item never ! 4952: Do not in any case make numbered backups; always make single backups. ! 4953: @end table ! 4954: ! 4955: @noindent ! 4956: @code{version-control} may be set locally in an individual buffer to ! 4957: control the making of backups for that buffer's file. For example, ! 4958: Rmail mode locally sets @code{version-control} to @code{never} to make sure ! 4959: that there is only one backup for an Rmail file. @xref{Locals}. ! 4960: ! 4961: @node Backup Deletion, Backup Copying, Backup Names, Backup ! 4962: @subsubsection Automatic Deletion of Backups ! 4963: ! 4964: @vindex kept-old-versions ! 4965: @vindex kept-new-versions ! 4966: To prevent unlimited consumption of disk space, Emacs can delete numbered ! 4967: backup versions automatically. Generally Emacs keeps the first few backups ! 4968: and the latest few backups, deleting any in between. This happens every ! 4969: time a new backup is made. The two variables that control the deletion are ! 4970: @code{kept-old-versions} and @code{kept-new-versions}. Their values are, respectively ! 4971: the number of oldest (lowest-numbered) backups to keep and the number of ! 4972: newest (highest-numbered) ones to keep, each time a new backup is made. ! 4973: Recall that these values are used just after a new backup version is made; ! 4974: that newly made backup is included in the count in @code{kept-new-versions}. ! 4975: By default, both variables are 2. ! 4976: ! 4977: @vindex trim-versions-without-asking ! 4978: If @code{trim-versions-without-asking} is non-@code{nil}, the excess ! 4979: middle versions are deleted without a murmur. If it is @code{nil}, the ! 4980: default, then you are asked whether the excess middle versions should ! 4981: really be deleted. ! 4982: ! 4983: Dired's @kbd{.} (Period) command can also be used to delete old versions. ! 4984: @xref{Dired}. ! 4985: ! 4986: @node Backup Copying,, Backup Deletion, Backup ! 4987: @subsubsection Copying vs.@: Renaming ! 4988: ! 4989: Backup files can be made by copying the old file or by renaming it. This ! 4990: makes a difference when the old file has multiple names. If the old file ! 4991: is renamed into the backup file, then the alternate names become names for ! 4992: the backup file. If the old file is copied instead, then the alternate ! 4993: names remain names for the file that you are editing, and the contents ! 4994: accessed by those names will be the new contents. ! 4995: ! 4996: The method of making a backup file may also affect the file's owner ! 4997: and group. If copying is used, these do not change. If renaming is used, ! 4998: you become the file's owner, and the file's group becomes the default ! 4999: (different operating systems have different defaults for the group). ! 5000: ! 5001: Having the owner change is usually a good idea, because then the owner ! 5002: always shows who last edited the file. Also, the owners of the backups ! 5003: show who produced those versions. Occasionally there is a file whose ! 5004: owner should not change; it is a good idea for such files to contain ! 5005: local variable lists to set @code{backup-by-copying-when-mismatch} for ! 5006: them alone (@pxref{File Variables}). ! 5007: ! 5008: @vindex backup-by-copying ! 5009: @vindex backup-by-copying-when-linked ! 5010: @vindex backup-by-copying-when-mismatch ! 5011: The choice of renaming or copying is controlled by three variables. ! 5012: Normally, renaming is done. If the variable @code{backup-by-copying} is ! 5013: non-@code{nil}, copying is used. Otherwise, if the variable ! 5014: @code{backup-by-copying-when-linked} is non-@code{nil}, then copying is ! 5015: done for files that have multiple names, but renaming may still done when ! 5016: the file being edited has only one name. If the variable ! 5017: @code{backup-by-copying-when-mismatch} is non-@code{nil}, then copying is ! 5018: done if renaming would cause the file's owner or group to change. @refill ! 5019: ! 5020: @node Interlocking,,Backup,Saving ! 5021: @subsection Protection against Simultaneous Editing ! 5022: ! 5023: @cindex file dates ! 5024: @cindex simultaneous editing ! 5025: Simultaneous editing occurs when two users visit the same file, both make ! 5026: changes, and then both save them. If nobody were informed that this was ! 5027: happening, whichever user saved first would later find that his changes ! 5028: were lost. On some systems, Emacs notices immediately when the second user ! 5029: starts to change the file, and issues an immediate warning. When this is ! 5030: not possible, or if the second user has gone on to change the file despite ! 5031: the warning, Emacs checks later when the file is saved, and issues a second ! 5032: warning when a user is about to overwrite a file containing another user's ! 5033: changes. If the editing user takes the proper corrective action at this ! 5034: point, he can prevent actual loss of work. ! 5035: ! 5036: @findex ask-user-about-lock ! 5037: When you make the first modification in an Emacs buffer that is visiting ! 5038: a file, Emacs records that you have locked the file. (It does this by ! 5039: writing another file in a directory reserved for this purpose.) The lock ! 5040: is removed when you save the changes. The idea is that the file is locked ! 5041: whenever the buffer is modified. If you begin to modify the buffer while ! 5042: the visited file is locked by someone else, this constitutes a collision, ! 5043: and Emacs asks you what to do. It does this by calling the Lisp function ! 5044: @code{ask-user-about-lock}, which you can redefine for the sake of ! 5045: customization. The standard definition of this function asks you a ! 5046: question and accepts three possible answers: ! 5047: ! 5048: @table @kbd ! 5049: @item s ! 5050: Steal the lock. Whoever was already changing the file loses the lock, ! 5051: and you gain the lock. ! 5052: @item p ! 5053: Proceed. Go ahead and edit the file despite its being locked by someone else. ! 5054: @item q ! 5055: Quit. This causes an error (@code{file-locked}) and the modification you ! 5056: were trying to make in the buffer does not actually take place. ! 5057: @end table ! 5058: ! 5059: Note that locking works on the basis of a file name; if a file has ! 5060: multiple names, Emacs does not realize that the two names are the same file ! 5061: and cannot prevent two user from editing it simultaneously under different ! 5062: names. However, basing locking on names means that Emacs can interlock the ! 5063: editing of new files that will not really exist until they are saved. ! 5064: ! 5065: Some systems are not configured to allow Emacs to make locks. On ! 5066: these systems, Emacs cannot detect trouble in advance, but it still can ! 5067: detect it in time to prevent you from overwriting someone else's changes. ! 5068: ! 5069: Every time Emacs saves a buffer, it first checks the last-modification ! 5070: date of the existing file on disk to see that it has not changed since the ! 5071: file was last visited or saved. If the date does not match, it implies ! 5072: that changes were made in the file in some other way, and these changes are ! 5073: about to be lost if Emacs actually does save. To prevent this, Emacs ! 5074: prints a warning message and asks for confirmation before saving. ! 5075: Occasionally you will know why the file was changed and know that it does ! 5076: not matter; then you can answer @kbd{yes} and proceed. Otherwise, you should ! 5077: cancel the save with @kbd{C-g} and investigate the situation. ! 5078: ! 5079: The first thing you should do when notified that simultaneous editing has ! 5080: already taken place is to list the directory with @kbd{C-u C-x C-d} ! 5081: (@pxref{ListDir,,Directory Listing}). This will show the file's current ! 5082: author. You should attempt to contact him to warn him not to continue ! 5083: editing. Often the next step is to save the contents of your Emacs buffer ! 5084: under a different name, and use @code{diff} to compare the two ! 5085: files.@refill ! 5086: ! 5087: Simultaneous editing checks are also made when you visit with @kbd{C-x ! 5088: C-f} a file that is already visited and when you start to modify a file. ! 5089: This is not strictly necessary, but it can cause you to find out about the ! 5090: problem earlier, when perhaps correction takes less work. ! 5091: ! 5092: @node Reverting, Auto Save, Saving, Files ! 5093: @section Reverting a Buffer ! 5094: @findex revert-buffer ! 5095: @cindex drastic changes ! 5096: ! 5097: If you have made extensive changes to a file and then change your mind ! 5098: about them, you can get rid of them by reading in the previous version of ! 5099: the file. To do this, use @kbd{M-x revert-buffer}, which operates on the ! 5100: current buffer. Since this is a very dangerous thing to do, you must ! 5101: confirm it with @kbd{yes}. ! 5102: ! 5103: If the current buffer has been auto-saved more recently than it has been ! 5104: saved for real, @code{revert-buffer} offers to read the auto save file ! 5105: instead of the visited file (@pxref{Auto Save}). This question comes ! 5106: before the usual request for confirmation, and demands @kbd{y} or @kbd{n} ! 5107: as an answer. If you have started to type @kbd{yes} for confirmation ! 5108: without realizing that the other question was going to be asked, the ! 5109: @kbd{y} will answer that question, but the @kbd{es} will not be valid ! 5110: confirmation. So you will have a chance to cancel the operation with ! 5111: @kbd{C-g} and try it again with the answers that you really intend. ! 5112: ! 5113: @code{revert-buffer} keeps point at the same distance (measured in ! 5114: characters) from the beginning of the file. If the file was edited only ! 5115: slightly, you will be at approximately the same piece of text after ! 5116: reverting as before. If you have made drastic changes, the same value of ! 5117: point in the old file may address a totally different piece of text. ! 5118: ! 5119: A buffer reverted from its visited file is marked ``not modified'' until ! 5120: another change is made. ! 5121: ! 5122: Some kinds of buffers whose contents reflect data bases other than files, ! 5123: such as Dired buffers, can also be reverted. For them, reverting means ! 5124: recalculating their contents from the appropriate data base. Buffers ! 5125: created randomly with @kbd{C-x b} cannot be reverted; @code{revert-buffer} ! 5126: reports an error when asked to do so. ! 5127: ! 5128: @node Auto Save, ListDir, Reverting, Files ! 5129: @section Auto-Saving: Protection Against Disasters ! 5130: @cindex Auto-Save mode ! 5131: @cindex crashes ! 5132: ! 5133: Emacs saves all the visited files from time to time (based on counting ! 5134: your keystrokes) without being asked. This is called @dfn{auto-saving}. ! 5135: It prevents you from losing more than a limited amount of work if the ! 5136: system crashes. ! 5137: ! 5138: When Emacs determines that it is time for auto-saving, each buffer is ! 5139: considered, and is auto-saved if auto-saving is turned on for it and it has ! 5140: been changed since the last time it was auto-saved. If any auto-saving is ! 5141: done, the message @samp{Auto-saving...} is displayed in the echo area until ! 5142: auto-saving is finished. Errors occurring during auto-saving are caught ! 5143: so that they do not interfere with the execution of commands you have been ! 5144: typing. ! 5145: ! 5146: @menu ! 5147: * Files: Auto Save Files. ! 5148: * Control: Auto Save Control. ! 5149: * Recover:: Recovering text from auto-save files. ! 5150: @end menu ! 5151: ! 5152: @node Auto Save Files, Auto Save Control, Auto Save, Auto Save ! 5153: @subsection Auto-Save Files ! 5154: ! 5155: Auto-saving does not normally save in the files that you visited, because ! 5156: it can be very undesirable to save a program that is in an inconsistent ! 5157: state when you have made half of a planned change. Instead, auto-saving ! 5158: is done in a different file called the @dfn{auto-save file}, and the ! 5159: visited file is changed only when you request saving explicitly (such as ! 5160: with @kbd{C-x C-s}). ! 5161: ! 5162: Normally, the auto-save file name is made by appending @samp{#} to the ! 5163: front and rear of the visited file name. Thus, a buffer visiting file ! 5164: @file{foo.c} would be auto-saved in a file @file{#foo.c#}. Most buffers ! 5165: that are not visiting files are auto-saved only if you request it ! 5166: explicitly; when they are auto-saved, the auto-save file name is made by ! 5167: appending @samp{#%} to the front and @samp{#} to the rear of buffer name. ! 5168: For example, the @samp{*mail*} buffer in which you compose messages to be ! 5169: sent is auto-saved in a file named @file{#%*mail*#}. Auto-save file names ! 5170: are made this way unless you reprogram parts of Emacs to do something ! 5171: different (the functions @code{make-auto-save-file-name} and ! 5172: @code{auto-save-file-name-p}). The file name to be used for auto-saving ! 5173: in a buffer is calculated when auto-saving is turned on in that buffer. ! 5174: ! 5175: @vindex auto-save-visited-file-name ! 5176: If you want auto-saving to be done in the visited file, set the variable ! 5177: @code{auto-save-visited-file-name} to be non-@code{nil}. In this mode, ! 5178: there is really no difference between auto-saving and explicit saving. ! 5179: ! 5180: @vindex delete-auto-save-files ! 5181: A buffer's auto-save file is deleted when you save the buffer in its ! 5182: visited file. To inhibit this, set the variable @code{delete-auto-save-files} ! 5183: to @code{nil}. Changing the visited file name with @kbd{C-x C-w} or ! 5184: @code{set-visited-file-name} renames any auto-save file to go with ! 5185: the new visited name. ! 5186: ! 5187: @node Auto Save Control, Recover, Auto Save Files, Auto Save ! 5188: @subsection Controlling Auto-Saving ! 5189: ! 5190: @vindex auto-save-default ! 5191: @findex auto-save-mode ! 5192: Each time you visit a file, auto-saving is turned on for that file's ! 5193: buffer if the variable @code{auto-save-default} is non-@code{nil} (but not ! 5194: in batch mode; @pxref{Entering Emacs}). The default for this variable is ! 5195: @code{t}, so auto-saving is the usual practice for file-visiting buffers. ! 5196: Auto-saving can be turned on or off for any existing buffer with the ! 5197: command @kbd{M-x auto-save-mode}. Like other minor mode commands, @kbd{M-x ! 5198: auto-save-mode} turns auto-saving on with a positive argument, off with a ! 5199: zero or negative argument; with no argument, it toggles. ! 5200: ! 5201: @vindex auto-save-interval ! 5202: @findex do-auto-save ! 5203: Emacs does auto-saving periodically based on counting how many characters ! 5204: you have typed since the last time auto-saving was done. The variable ! 5205: @code{auto-save-interval} specifies how many characters there are between ! 5206: auto-saves. By default, it is 300. Emacs also auto-saves whenever you ! 5207: call the function @code{do-auto-save}. ! 5208: ! 5209: Emacs also does auto-saving whenever it gets a fatal error. This ! 5210: includes killing the Emacs job with a shell command such as @code{kill ! 5211: %emacs}, or disconnecting a phone line or network connection. ! 5212: ! 5213: @node Recover,, Auto Save Control, Auto Save ! 5214: @subsection Recovering Data from Auto-Saves ! 5215: ! 5216: @findex recover-file ! 5217: The way to use the contents of an auto-save file to recover from a loss ! 5218: of data is with the command @kbd{M-x recover-file @key{RET} @var{file} ! 5219: @key{RET}}. This visits @var{file} and then (after your confirmation) ! 5220: restores the contents from from its auto-save file @file{#@var{file}#}. You ! 5221: can then save with @kbd{C-x C-s} to put the recovered text into @var{file} ! 5222: itself. For example, to recover file @file{foo.c} from its auto-save file ! 5223: @file{#foo.c#}, do:@refill ! 5224: ! 5225: @example ! 5226: M-x recover-file @key{RET} foo.c @key{RET} ! 5227: C-x C-s ! 5228: @end example ! 5229: ! 5230: Before asking for confirmation, @kbd{M-x recover-file} displays a ! 5231: directory listing describing the specified file and the auto-save file, ! 5232: so you can compare their sizes and dates. If the auto-save file ! 5233: is older, @kbd{M-x recover-file} does not offer to read it. ! 5234: ! 5235: Auto-saving is disabled by @kbd{M-x recover-file} because using ! 5236: this command implies that the auto-save file contains valuable data ! 5237: from a past session. If you save the data in the visited file and ! 5238: then go on to make new changes, you should turn auto-saving back on ! 5239: with @kbd{M-x auto-save-mode}. ! 5240: ! 5241: @node ListDir, Dired, Auto Save, Files ! 5242: @section Listing a File Directory ! 5243: ! 5244: @cindex file directory ! 5245: @cindex directory listing ! 5246: Files are classified by Unix into @dfn{directories}. A @dfn{directory ! 5247: listing} is a list of all the files in a directory. Emacs provides ! 5248: directory listings in brief format (file names only) and verbose format ! 5249: (sizes, dates, and authors included). ! 5250: ! 5251: @table @kbd ! 5252: @item C-x C-d @var{dir-or-pattern} ! 5253: Print a brief directory listing (@code{list-directory}). ! 5254: @item C-u C-x C-d @var{dir-or-pattern} ! 5255: Print a verbose directory listing. ! 5256: @end table ! 5257: ! 5258: @findex list-directory ! 5259: @kindex C-x C-d ! 5260: The command to print a directory listing is @kbd{C-x C-d} (@code{list-directory}). ! 5261: It reads using the minibuffer a file name which is either a directory to be ! 5262: listed or a wildcard-containing pattern for the files to be listed. For ! 5263: example, ! 5264: ! 5265: @example ! 5266: C-x C-d /u2/emacs/etc @key{RET} ! 5267: @end example ! 5268: ! 5269: @noindent ! 5270: lists all the files in directory @file{/u2/emacs/etc}. An example of ! 5271: specifying a file name pattern is ! 5272: ! 5273: @example ! 5274: C-x C-d /u2/emacs/src/*.c @key{RET} ! 5275: @end example ! 5276: ! 5277: Normally, @kbd{C-x C-d} prints a brief directory listing containing just ! 5278: file names. A numeric argument (regardless of value) tells it to print a ! 5279: verbose listing (like @code{ls -l}). ! 5280: ! 5281: @vindex list-directory-brief-switches ! 5282: @vindex list-directory-verbose-switches ! 5283: The text of a directory listing is obtained by running @code{ls} in an ! 5284: inferior process. Two Emacs variables control the switches passed to ! 5285: @code{ls}: @code{list-directory-brief-switches} is a string giving the ! 5286: switches to use in brief listings (@code{"-CF"} by default), and ! 5287: @code{list-directory-verbose-switches} is a string giving the switches to ! 5288: use in a verbose listing (@code{"-l"} by default). ! 5289: ! 5290: @node Dired, Misc File Ops, ListDir, Files ! 5291: @section Dired, the Directory Editor ! 5292: @cindex Dired ! 5293: @cindex deletion (of files) ! 5294: ! 5295: Dired makes it easy to delete or visit many of the files in a single ! 5296: directory at once. It makes an Emacs buffer containing a listing of the ! 5297: directory. You can use the normal Emacs commands to move around in this ! 5298: buffer, and special Dired commands to operate on the files. ! 5299: ! 5300: @menu ! 5301: * Enter: Dired Enter. How to invoke Dired. ! 5302: * Edit: Dired Edit. Editing the Dired buffer. ! 5303: * Deletion: Dired Deletion. Deleting files with Dired. ! 5304: * Immed: Dired Immed. Other file operations through Dired. ! 5305: @end menu ! 5306: ! 5307: @node Dired Enter, Dired Edit, Dired, Dired ! 5308: @subsection Entering Dired ! 5309: ! 5310: @findex dired ! 5311: @kindex C-x d ! 5312: @vindex dired-listing-switches ! 5313: To invoke dired, do @kbd{C-x d} or @kbd{M-x dired}. The command reads a ! 5314: directory name or wildcard file name pattern as a minibuffer argument just ! 5315: like the @code{list-directory} command, @kbd{C-x C-d}. Where @code{dired} ! 5316: differs from @code{list-directory} is in naming the buffer after the ! 5317: directory name or the wildcard pattern used for the listing, and putting ! 5318: the buffer into Dired mode so that the special commands of Dired are ! 5319: available in it. The variable @code{dired-listing-switches} is a string ! 5320: used as an argument to @code{ls} in making the directory; this string ! 5321: @i{must} contain @samp{-l}. ! 5322: ! 5323: @findex dired-other-window ! 5324: @kindex C-x 4 d ! 5325: To display the Dired buffer in another window rather than in the selected ! 5326: window, use @kbd{C-x 4 d} (@code{dired-other-window)} instead of @kbd{C-x d}. ! 5327: ! 5328: @node Dired Edit, Dired Deletion, Dired Enter, Dired ! 5329: @subsection Editing in Dired ! 5330: ! 5331: Once the Dired buffer exists, you can switch freely between it and other ! 5332: Emacs buffers. Whenever the Dired buffer is selected, certain special ! 5333: commands are provided that operate on files that are listed. The Dired ! 5334: buffer is ``read-only'', and inserting text in it is not useful, so ! 5335: ordinary printing characters such as @kbd{d} and @kbd{x} are used for Dired ! 5336: commands. Most Dired commands operate on the file described by the line ! 5337: that point is on. Some commands perform operations immediately; others ! 5338: ``flag'' the file to be operated on later. ! 5339: ! 5340: Most Dired commands that operate on the current line's file also treat a ! 5341: numeric argument as a repeat count, meaning to act on the files of the ! 5342: next few lines. A negative argument means to operate on the files of the ! 5343: preceding lines, and leave point on the first of those lines. ! 5344: ! 5345: All the usual Emacs cursor motion commands are available in Dired ! 5346: buffers. Some special purpose commands are also provided. The keys ! 5347: @kbd{C-n} and @kbd{C-p} are redefined so that they try to position ! 5348: the cursor at the beginning of the filename on the line, rather than ! 5349: at the beginning of the line. ! 5350: ! 5351: For extra convenience, @key{SPC} and @kbd{n} in Dired are equivalent to ! 5352: @kbd{C-n}. @kbd{p} is equivalent to @kbd{C-p}. Moving by lines is done so ! 5353: often in Dired that it deserves to be easy to type. @key{DEL} (move up and ! 5354: unflag) is often useful simply for moving up.@refill ! 5355: ! 5356: The @kbd{g} command in Dired runs @code{revert-buffer} to reinitialize ! 5357: the buffer from the actual disk directory and show any changes made in the ! 5358: directory by programs other than Dired. All deletion flags in the Dired ! 5359: buffer are lost when this is done. ! 5360: ! 5361: @node Dired Deletion, Dired Immed, Dired Edit, Dired ! 5362: @subsection Deleting Files with Dired ! 5363: ! 5364: The primary use of Dired is to flag files for deletion and then delete ! 5365: them. ! 5366: ! 5367: @table @kbd ! 5368: @item d ! 5369: Flag this file for deletion. ! 5370: @item u ! 5371: Remove deletion-flag on this line. ! 5372: @item @key{DEL} ! 5373: Remove deletion-flag on previous line, moving point to that line. ! 5374: @item x ! 5375: Delete the files that are flagged for deletion. ! 5376: @item # ! 5377: Flag all auto-save files (files whose names start and end with @samp{#}) ! 5378: for deletion (@pxref{Auto Save}). ! 5379: @item ~ ! 5380: Flag all backup files (files whose names end with @samp{~}) for deletion ! 5381: (@pxref{Backup}). ! 5382: @item .@: @r{(Period)} ! 5383: Flag excess numeric backup files for deletion. The oldest and newest ! 5384: few backup files of any one file are exempt; the middle ones are flagged. ! 5385: @end table ! 5386: ! 5387: You can flag a file for deletion by moving to the line describing the ! 5388: file and typing @kbd{d} or @kbd{C-d}. The deletion flag is visible as a ! 5389: @samp{D} at the beginning of the line. Point is moved to the beginning of ! 5390: the next line, so that repeated @kbd{d} commands flag successive files. ! 5391: ! 5392: The files are flagged for deletion rather than deleted immediately to ! 5393: avoid the danger of deleting a file accidentally. Until you direct Dired ! 5394: to delete the flagged files, you can remove deletion flags using the ! 5395: commands @kbd{u} and @key{DEL}. @kbd{u} works just like @kbd{d}, but ! 5396: removes flags rather than making flags. @key{DEL} moves upward, removing ! 5397: flags; it is like @kbd{u} with numeric argument automatically negated. ! 5398: ! 5399: To delete the flagged files, type @kbd{x}. This command first displays a ! 5400: list of all the file names flagged for deletion, and requests confirmation ! 5401: with @kbd{yes}. Once you confirm, all the flagged files are deleted, and their ! 5402: lines are deleted from the text of the Dired buffer. The shortened Dired ! 5403: buffer remains selected. If you answer @kbd{no} or quit with @kbd{C-g}, you ! 5404: return immediately to Dired, with the deletion flags still present and no ! 5405: files actually deleted. ! 5406: ! 5407: The @kbd{#}, @kbd{~} and @kbd{.} commands flag many files for ! 5408: deletion, based on their names. These commands are useful precisely ! 5409: because they do not actually delete any files; you can remove the ! 5410: deletion flags from any flagged files that you really wish to keep.@refill ! 5411: ! 5412: @kbd{#} flags for deletion all files that appear to have been made by ! 5413: auto-saving (that is, files whose names begin and end with @samp{#}). ! 5414: @kbd{~} flags for deletion all files that appear to have been made as ! 5415: backups for files that were edited (that is, files whose names end with ! 5416: @samp{~}). ! 5417: ! 5418: @vindex dired-kept-versions ! 5419: @kbd{.} (Period) flags just some of the backup files for deletion: only ! 5420: numeric backups that are not among the oldest few nor the newest few ! 5421: backups of any one file. Normally @code{dired-kept-versions} (not ! 5422: @code{kept-new-versions}; that applies only when saving) specifies the ! 5423: number of newest versions of each file to keep, and ! 5424: @code{kept-old-versions} specifies the number of oldest versions to keep. ! 5425: Period with a positive numeric argument, as in @kbd{C-u 3 .}, specifies the ! 5426: number of newest versions to keep, overriding @code{dired-kept-versions}. ! 5427: A negative numeric argument overrides @code{kept-old-versions}, using minus ! 5428: the value of the argument to specify the number of oldest versions of each ! 5429: file to keep.@refill ! 5430: ! 5431: @node Dired Immed,, Dired Deletion, Dired ! 5432: @subsection Immediate File Operations in Dired ! 5433: ! 5434: Some file operations in Dired take place immediately when they are ! 5435: requested. ! 5436: ! 5437: @table @kbd ! 5438: @item c ! 5439: Copies the file described on the current line. You must supply a file name ! 5440: to copy to, using the minibuffer. ! 5441: @item f ! 5442: Visits the file described on the current line. It is just like typing ! 5443: @kbd{C-x C-f} and supplying that file name. If the file on this line is a ! 5444: subdirectory, @kbd{f} actually causes Dired to be invoked on that ! 5445: subdirectory. @xref{Visiting}. ! 5446: @item o ! 5447: Like @kbd{f}, but uses another window to display the file's buffer. The ! 5448: Dired buffer remains visible in the first window. This is like using ! 5449: @kbd{C-x 4 C-f} to visit the file. @xref{Windows}. ! 5450: @item r ! 5451: Renames the file described on the current line. You must supply a file ! 5452: name to rename to, using the minibuffer. ! 5453: @item v ! 5454: Views the file described on this line using @kbd{M-x view-file}. Viewing a ! 5455: file is like visiting it, but is slanted toward moving around in the file ! 5456: conveniently and does not allow changing the file. @xref{Misc File ! 5457: Ops,View File}. Viewing a file that is a directory runs Dired on that ! 5458: directory.@refill ! 5459: @end table ! 5460: ! 5461: @node Misc File Ops,, Dired, Files ! 5462: @section Miscellaneous File Operations ! 5463: ! 5464: Emacs has commands for performing many other operations on files. ! 5465: All operate on one file; they do not accept wild card file names. ! 5466: ! 5467: @findex view-file ! 5468: @cindex viewing ! 5469: @kbd{M-x view-file} allows you to scan or read a file by sequential ! 5470: screenfuls. It reads a file name argument using the minibuffer. After ! 5471: reading the file into an Emacs buffer, @code{view-file} reads and displays ! 5472: one windowful. You can then type @key{SPC} to scroll forward one windowful, ! 5473: or @key{DEL} to scroll backward. Various other commands are provided for ! 5474: moving around in the file, but none for changing it; type @kbd{C-h} while ! 5475: viewing for a list of them. They are mostly the same as normal Emacs ! 5476: cursor motion commands. To exit from viewing, type @kbd{C-c}. ! 5477: ! 5478: @findex insert-file ! 5479: @kbd{M-x insert-file} inserts a copy of the contents of the specified ! 5480: file into the current buffer at point, leaving point unchanged before the ! 5481: contents and the mark after them. @xref{Mark}. ! 5482: ! 5483: @findex write-region ! 5484: @findex append-to-file ! 5485: @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it copies ! 5486: the contents of the region into the specified file. @kbd{M-x append-to-file} ! 5487: adds the text of the region to the end of the specified file. ! 5488: ! 5489: @findex delete-file ! 5490: @cindex deletion (of files) ! 5491: @kbd{M-x delete-file} deletes the specified file, like the @code{rm} ! 5492: command in the shell. If you are deleting many files in one directory, it ! 5493: may be more convenient to use Dired (@pxref{Dired}). ! 5494: ! 5495: @findex rename-file ! 5496: @kbd{M-x rename-file} reads two file names @var{old} and @var{new} using ! 5497: the minibuffer, then renames file @var{old} as @var{new}. If a file named ! 5498: @var{new} already exists, you must confirm with @kbd{yes} or renaming is not ! 5499: done; this is because renaming causes the old meaning of the name @var{new} ! 5500: to be lost. If @var{old} and @var{new} are on different file systems, the ! 5501: file @var{old} is copied and deleted. ! 5502: ! 5503: @findex add-name-to-file ! 5504: The similar command @kbd{M-x add-name-to-file} is used to add an ! 5505: additional name to an existing file without removing its old name. ! 5506: The new name must belong on the same file system that the file is on. ! 5507: ! 5508: @findex copy-file ! 5509: @cindex copying files ! 5510: @kbd{M-x copy-file} reads the file @var{old} and writes a new file named ! 5511: @var{new} with the same contents. Confirmation is required if a file named ! 5512: @var{new} already exists, because copying has the consequence of overwriting ! 5513: the old contents of the file @var{new}. ! 5514: ! 5515: @findex make-symbolic-link ! 5516: @kbd{M-x make-symbolic-link} reads two file names @var{old} and @var{linkname}, ! 5517: and then creates a symbolic link named @var{linkname} and pointing at @var{old}. ! 5518: The effect is that future attempts to open file @var{linkname} will refer ! 5519: to whatever file is named @var{old} at the time the opening is done, or ! 5520: will get an error if the name @var{old} is not in use at that time. ! 5521: Confirmation is required when creating the link if @var{linkname} is in ! 5522: use. Note that not all systems support symbolic links. ! 5523: ! 5524: @node Buffers, Windows, Files, Top ! 5525: @chapter Using Multiple Buffers ! 5526: ! 5527: @cindex buffers ! 5528: The text you are editing in Emacs resides in an object called a ! 5529: @dfn{buffer}. Each time you visit a file, a buffer is created to hold the ! 5530: file's text. Each time you invoke Dired, a buffer is created to hold the ! 5531: directory listing. If you send a message with @kbd{C-x m}, a buffer named ! 5532: @samp{*mail*} is used to hold the text of the message. When you ask for a ! 5533: command's documentation, that appears in a buffer called @samp{*Help*}. ! 5534: ! 5535: @cindex selected buffer ! 5536: @cindex current buffer ! 5537: At any time, one and only one buffer is @dfn{selected}. It is also ! 5538: called the @dfn{current buffer}. Often we say that a command operates on ! 5539: ``the buffer'' as if there were only one; but really this means that the ! 5540: command operates on the selected buffer (most commands do). ! 5541: ! 5542: When Emacs makes multiple windows, each window has a chosen buffer which ! 5543: is displayed there, but at any time only one of the windows is selected and ! 5544: its chosen buffer is the selected buffer. Each window's mode line displays ! 5545: the name of the buffer that the window is displaying (@pxref{Windows}). ! 5546: ! 5547: Each buffer has a name, which can be of any length, and you can select ! 5548: any buffer by giving its name. Most buffers are made by visiting files, ! 5549: and their names are derived from the files' names. But you can also create ! 5550: an empty buffer with any name you want. A newly started Emacs has a buffer ! 5551: named @samp{*scratch*} which can be used for evaluating Lisp expressions in ! 5552: Emacs. The distinction between upper and lower case matters in buffer ! 5553: names. ! 5554: ! 5555: Each buffer records individually what file it is visiting, whether it is ! 5556: modified, and what major mode and minor modes are in effect in it ! 5557: (@pxref{Major Modes}). Any Emacs variable can be made @dfn{local to} a ! 5558: particular buffer, meaning its value in that buffer can be different from ! 5559: the value in other buffers. @xref{Locals}. ! 5560: ! 5561: @menu ! 5562: * Select Buffer:: Creating a new buffer or reselecting an old one. ! 5563: * List Buffers:: Getting a list of buffers that exist. ! 5564: * Misc Buffer:: Renaming; changing read-onliness; copying text. ! 5565: * Kill Buffer:: Killing buffers you no longer need. ! 5566: * Several Buffers:: How to go through the list of all buffers ! 5567: and operate variously on several of them. ! 5568: @end menu ! 5569: ! 5570: @node Select Buffer, List Buffers, Buffers, Buffers ! 5571: @section Creating and Selecting Buffers ! 5572: @cindex change buffers ! 5573: @cindex switch buffers ! 5574: ! 5575: @table @kbd ! 5576: @item C-x b @var{buffer} @key{RET} ! 5577: Select or create a buffer named @var{buffer} (@code{switch-to-buffer}). ! 5578: @item C-x 4 b @var{buffer} @key{RET} ! 5579: Similar but select a buffer named @var{buffer} in another window ! 5580: (@code{switch-to-buffer-other-window}). ! 5581: @end table ! 5582: ! 5583: @kindex C-x 4 b ! 5584: @findex switch-to-buffer-other-window ! 5585: @kindex C-x b ! 5586: @findex switch-to-buffer ! 5587: To select the buffer named @var{bufname}, type @kbd{C-x b @var{bufname} ! 5588: @key{RET}}. This is the command @code{switch-to-buffer} with argument ! 5589: @var{bufname}. You can use completion on an abbreviation for the buffer ! 5590: name you want (@pxref{Completion}). An empty argument to @kbd{C-x b} ! 5591: specifies the most recently selected buffer that is not displayed in any ! 5592: window.@refill ! 5593: ! 5594: Most buffers are created by visiting files, or by Emacs commands that ! 5595: want to display some text, but you can also create a buffer explicitly by ! 5596: typing @kbd{C-x b @var{bufname} @key{RET}}. This makes a new, empty buffer which ! 5597: is not visiting any file, and selects it for editing. Such buffers are ! 5598: used for making notes to yourself. If you try to save one, you are asked ! 5599: for the file name to use. The new buffer's major mode is determined by the ! 5600: value of @code{default-major-mode} (@pxref{Major Modes}). ! 5601: ! 5602: Note that @kbd{C-x C-f}, and any other command for visiting a file, can ! 5603: also be used to switch buffers. @xref{Visiting}. ! 5604: ! 5605: @node List Buffers, Misc Buffer, Select Buffer, Buffers ! 5606: @section Listing Existing Buffers ! 5607: ! 5608: @table @kbd ! 5609: @item C-x C-b ! 5610: List the existing buffers (@code{list-buffers}). ! 5611: @end table ! 5612: ! 5613: @kindex C-x C-b ! 5614: @findex list-buffers ! 5615: To print a list of all the buffers that exist, type @kbd{C-x C-b}. ! 5616: Each line in the list shows one buffer's name, major mode and visited file. ! 5617: @samp{*} at the beginning of a line indicates the buffer is ``modified''. ! 5618: If several buffers are modified, it may be time to save some with @kbd{C-x ! 5619: s} (@pxref{Saving}). @samp{%} indicates a read-only buffer. @samp{.} ! 5620: marks the selected buffer. Here is an example of a buffer list:@refill ! 5621: ! 5622: @smallexample ! 5623: MR Buffer Size Mode File ! 5624: -- ------ ---- ---- ---- ! 5625: .* emacs.tex 383402 Texinfo /u2/emacs/man/emacs.tex ! 5626: *Help* 1287 Fundamental ! 5627: files.el 23076 Emacs-Lisp /u2/emacs/lisp/files.el ! 5628: % RMAIL 64042 RMAIL /u/rms/RMAIL ! 5629: *% man 747 Dired ! 5630: net.emacs 343885 Fundamental /u/rms/net.emacs ! 5631: fileio.c 27691 C /u2/emacs/src/fileio.c ! 5632: NEWS 67340 Text /u2/emacs/etc/NEWS ! 5633: *scratch* 0 Lisp Interaction ! 5634: @end smallexample ! 5635: ! 5636: @noindent ! 5637: Note that the buffer @samp{*Help*} was made by a help request; it is not ! 5638: visiting any file. The buffer @code{man} was made by Dired on the ! 5639: directory @file{/u2/emacs/man/}. ! 5640: ! 5641: @node Misc Buffer, Kill Buffer, List Buffers, Buffers ! 5642: @section Miscellaneous Buffer Operations ! 5643: ! 5644: @table @kbd ! 5645: @item C-x C-q ! 5646: Toggle read-only status of buffer (@code{toggle-read-only}). ! 5647: @item M-x rename-buffer ! 5648: Change the name of the current buffer. ! 5649: @item M-x view-buffer ! 5650: Scroll through a buffer. ! 5651: @end table ! 5652: ! 5653: @cindex read-only buffer ! 5654: @kindex C-x C-q ! 5655: @findex toggle-read-only ! 5656: @vindex buffer-read-only ! 5657: A buffer can be @dfn{read-only}, which means that commands to change its ! 5658: text are not allowed. Normally, read-only buffers are made by subsystems ! 5659: such as Dired and Rmail that have special commands to operate on the text; ! 5660: a read-only buffer is also made if you visit a file that is protected so ! 5661: you cannot write it. If you wish to make changes in a read-only buffer, ! 5662: use the command @kbd{C-x C-q} (@code{toggle-read-only}). It makes a ! 5663: read-only buffer writable, and makes a writable buffer read-only. This ! 5664: works by setting the variable @code{buffer-read-only}, which has a local ! 5665: value in each buffer and makes the buffer read-only if its value is ! 5666: non-@code{nil}. ! 5667: ! 5668: @findex rename-buffer ! 5669: @kbd{M-x rename-buffer} changes the name of the current buffer. Specify ! 5670: the new name as a minibuffer argument. There is no default. If you ! 5671: specify a name that is in use for some other buffer, an error happens and ! 5672: no renaming is done. ! 5673: ! 5674: @findex view-buffer ! 5675: @kbd{M-x view-buffer} is much like @kbd{M-x view-file} (@pxref{Misc File Ops}) ! 5676: except that it examines an already existing Emacs buffer. View mode ! 5677: provides commands for scrolling through the buffer conveniently but not ! 5678: for changing it. When you exit View mode, the value of point that resulted ! 5679: from your perusal remains in effect. ! 5680: ! 5681: The commands @kbd{C-x a} (@code{append-to-buffer}) and @kbd{M-x ! 5682: insert-buffer} can be used to copy text from one buffer to another. ! 5683: @xref{Accumulating Text}.@refill ! 5684: ! 5685: @node Kill Buffer, Several Buffers, Misc Buffer, Buffers ! 5686: @section Killing Buffers ! 5687: ! 5688: After you use Emacs for a while, you may accumulate a large number of ! 5689: buffers. You may then find it convenient to eliminate the ones you no ! 5690: longer need. There are several commands provided for doing this. ! 5691: ! 5692: @c WideCommands ! 5693: @table @kbd ! 5694: @item C-x k ! 5695: Kill a buffer, specified by name (@code{kill-buffer}). ! 5696: @item M-x kill-some-buffers ! 5697: Offer to kill each buffer, one by one. ! 5698: @end table ! 5699: ! 5700: @findex kill-buffer ! 5701: @findex kill-some-buffers ! 5702: @kindex C-x k ! 5703: ! 5704: @kbd{C-x k} (@code{kill-buffer}) kills one buffer, whose name you specify ! 5705: in the minibuffer. The default, used if you type just @key{RET} in the ! 5706: minibuffer, is to kill the current buffer. If the current buffer is ! 5707: killed, another buffer is selected; a buffer that has been selected ! 5708: recently but does not appear in any window now is chosen to be selected. ! 5709: If the buffer being killed is modified (has unsaved editing) then you are ! 5710: asked to confirm with @kbd{yes} before the buffer is killed. ! 5711: ! 5712: The command @kbd{M-x kill-some-buffers} asks about each buffer, one by ! 5713: one. An answer of @kbd{y} means to kill the buffer. Killing the current ! 5714: buffer or a buffer containing unsaved changes selects a new buffer or asks ! 5715: for confirmation just like @code{kill-buffer}. ! 5716: ! 5717: @node Several Buffers,, Kill Buffer, Buffers ! 5718: @section Operating on Several Buffers ! 5719: @cindex buffer menu ! 5720: ! 5721: The @dfn{buffer-menu} facility is like a ``Dired for buffers''; it allows ! 5722: you to request operations on various Emacs buffers by editing an Emacs ! 5723: buffer containing a list of them. You can save buffers, kill them ! 5724: (here called @dfn{deleting} them, for consistency with Dired), or display ! 5725: them. ! 5726: ! 5727: @table @kbd ! 5728: @item M-x buffer-menu ! 5729: Begin editing a buffer listing all Emacs buffers. ! 5730: @end table ! 5731: ! 5732: @findex buffer-menu ! 5733: The command @code{buffer-menu} writes a list of all Emacs buffers into ! 5734: the buffer @samp{*Buffer List*}, and selects that buffer in Buffer Menu ! 5735: mode. The buffer is read-only, and can only be changed through the special ! 5736: commands described in this section. Most of these commands are graphic ! 5737: characters. The usual Emacs cursor motion commands can be used in the ! 5738: @samp{*Buffer List*} buffer. The following special commands apply to the ! 5739: buffer described on the current line. ! 5740: ! 5741: @table @kbd ! 5742: @item d ! 5743: Request to delete (kill) the buffer, then move down. The request ! 5744: shows as a @samp{D} on the line, before the buffer name. Requested ! 5745: deletions take place when the @kbd{x} command is used. ! 5746: @item k ! 5747: Synonym for @kbd{d}. ! 5748: @item C-d ! 5749: Like @kbd{d} but move up afterwards instead of down. ! 5750: @item s ! 5751: Request to save the buffer. The request shows as an @samp{S} on the ! 5752: line. Requested saves take place when the @kbd{x} command is used. ! 5753: You may request both saving and deletion for the same buffer. ! 5754: @item ~ ! 5755: Mark buffer ``unmodified''. The command @kbd{~} does this ! 5756: immediately when typed. ! 5757: @item x ! 5758: Perform previously requested deletions and saves. ! 5759: @item u ! 5760: Remove any request made for the current line, and move down. ! 5761: @item @key{DEL} ! 5762: Move to previous line and remove any request made for that line. ! 5763: @end table ! 5764: ! 5765: All the commands that put in or remove flags to request later operations ! 5766: also move down a line, and accept a numeric argument as a repeat count, ! 5767: unless otherwise specified. ! 5768: ! 5769: There are also special commands to use the buffer list to select another ! 5770: buffer, and to specify one or more other buffers for display in additional ! 5771: windows. ! 5772: ! 5773: @table @kbd ! 5774: @item 1 ! 5775: Select the buffer in a full-screen window. This command takes effect ! 5776: immediately. ! 5777: @item 2 ! 5778: Immediately set up two windows, with this buffer in one, and the ! 5779: previously selected buffer (aside from the buffer @samp{*Buffer List*}) ! 5780: in the other. ! 5781: @item f ! 5782: Immediately select the buffer in place of the @samp{*Buffer List*} buffer. ! 5783: @item o ! 5784: Immediately select the buffer in another window as if by @kbd{C-x 4 b}, ! 5785: leaving @samp{*Buffer List*} visible. ! 5786: @item q ! 5787: Immediately select this buffer, and also display in other windows any ! 5788: buffers previously flagged with the @kbd{m} command. If there are no ! 5789: such buffers, this command is equivalent to @kbd{1}. ! 5790: @item m ! 5791: Flag this buffer to be displayed in another window if the @kbd{q} ! 5792: command is used. The request shows as a @samp{>} at the beginning of ! 5793: the line. The same buffer may not have both a delete request and a ! 5794: display request. ! 5795: @end table ! 5796: ! 5797: All that @code{buffer-menu} does directly is create and select a suitable ! 5798: buffer, and turn on Buffer Menu mode. Everything else described above is ! 5799: implemented by the special commands provided in Buffer Menu mode. One ! 5800: consequence of this is that you can switch from the @samp{*Buffer List*} ! 5801: buffer to another Emacs buffer, and edit there. You can reselect the ! 5802: @code{buffer-menu} buffer later, to perform the operations already ! 5803: requested, or you can kill it, or pay no further attention to it. ! 5804: ! 5805: The only difference between @code{buffer-menu} and @code{list-buffers} is ! 5806: that @code{buffer-menu} selects the @samp{*Buffer List*} buffer and ! 5807: @code{list-buffers} does not. If you run @code{list-buffers} (that is, ! 5808: type @kbd{C-x C-b}) and select the buffer list manually, you can use all of ! 5809: the commands described here. ! 5810: ! 5811: @node Windows, Major Modes, Buffers, Top ! 5812: @chapter Multiple Windows ! 5813: @cindex windows ! 5814: ! 5815: Emacs can split the screen into two or many windows, which can display ! 5816: parts of different buffers, or different parts of one buffer. ! 5817: ! 5818: @menu ! 5819: * Basic Window:: Introduction to Emacs windows. ! 5820: * Split Window:: New windows are made by splitting existing windows. ! 5821: * Other Window:: Moving to another window or doing something to it. ! 5822: * Pop Up Window:: Finding a file or buffer in another window. ! 5823: * Change Window:: Deleting windows and changing their sizes. ! 5824: @end menu ! 5825: ! 5826: @node Basic Window, Split Window, Windows, Windows ! 5827: @section Concepts of Emacs Windows ! 5828: ! 5829: When multiple windows are being displayed, each window has an Emacs ! 5830: buffer designated for display in it. The same buffer may appear in more ! 5831: than one window; if it does, any changes in its text are displayed in all ! 5832: the windows where it appears. But the windows showing the same buffer can ! 5833: show different parts of it, because each window has its own value of point. ! 5834: ! 5835: @cindex selected window ! 5836: At any time, one of the windows is the @dfn{selected window}; the buffer ! 5837: this window is displaying is the current buffer. The terminal's cursor ! 5838: shows the location of point in this window. Each other window has a ! 5839: location of point as well, but since the terminal has only one cursor there ! 5840: is no way to show where those locations are. ! 5841: ! 5842: Commands to move point affect the value of point for the selected Emacs ! 5843: window only. They do not change the value of point in any other Emacs ! 5844: window, even one showing the same buffer. The same is true for commands ! 5845: such as @kbd{C-x b} to change the selected buffer in the selected window; ! 5846: they do not affect other windows at all. However, there are other commands ! 5847: such as @kbd{C-x 4 b} that select a different window and switch buffers in ! 5848: it. Also, all commands that display information in a window, including ! 5849: (for example) @kbd{C-h f} (@code{describe-function}) and @kbd{C-x C-b} ! 5850: (@code{list-buffers}), work by switching buffers in a nonselected window ! 5851: without affecting the selected window. ! 5852: ! 5853: Each window has its own mode line, which displays the buffer name, ! 5854: modification status and major and minor modes of the buffer that is ! 5855: displayed in the window. @xref{Mode Line}, for full details on the mode ! 5856: line. ! 5857: ! 5858: @node Split Window, Other Window, Basic Window, Windows ! 5859: @section Splitting Windows ! 5860: ! 5861: @table @kbd ! 5862: @item C-x 2 ! 5863: Split the selected window into two windows, one above the other ! 5864: (@code{split-window-vertically}). ! 5865: @item C-x 5 ! 5866: Split the selected window into two windows positioned side by side ! 5867: (@code{split-window-horizontally}). ! 5868: @end table ! 5869: ! 5870: @kindex C-x 2 ! 5871: @findex split-window-vertically ! 5872: The command @kbd{C-x 2} (@code{split-window-vertically}) breaks the ! 5873: selected window into two windows, one above the other. Both windows start ! 5874: out displaying the same buffer, with the same value of point. By default ! 5875: the two windows each get half the height of the window that was split; a ! 5876: numeric argument specifies how many lines to give to the top window. ! 5877: ! 5878: @kindex C-x 5 ! 5879: @findex split-window-horizontally ! 5880: @kbd{C-x 5} (@code{split-window-horizontally}) breaks the selected ! 5881: window into two side-by-side windows. A numeric argument specifies ! 5882: how many columns to give the one on the left. A line of vertical bars ! 5883: separates the two windows. Windows that are not the full width of the ! 5884: screen have mode lines, but they are truncated; also, they do not ! 5885: always appear in inverse video, because, the Emacs display routines ! 5886: have not been taught how to display a region of inverse video that is ! 5887: only part of a line on the screen. ! 5888: ! 5889: @vindex truncate-partial-width-windows ! 5890: When a window is less than the full width, text lines too long to fit are ! 5891: frequent. Continuing all those lines might be confusing. The variable ! 5892: @code{truncate-partial-width-windows} can be set non-@code{nil} to force ! 5893: truncation in all windows less than the full width of the screen, ! 5894: independent of the buffer being displayed and its value for ! 5895: @code{truncate-lines}. @xref{Continuation Lines}.@refill ! 5896: ! 5897: Horizontal scrolling is often used in side-by-side windows. ! 5898: @xref{Display}. ! 5899: ! 5900: @node Other Window, Pop Up Window, Split Window, Windows ! 5901: @section Using Other Windows ! 5902: ! 5903: @table @kbd ! 5904: @item C-x o ! 5905: Select another window (@code{other-window}). That is @kbd{o}, not zero. ! 5906: @item C-M-v ! 5907: Scroll the next window (@code{scroll-other-window}). ! 5908: @item M-x compare-windows ! 5909: Find next place where the text in the selected window does not match ! 5910: the text in the next window. ! 5911: @end table ! 5912: ! 5913: @kindex C-x o ! 5914: @findex other-window ! 5915: To select a different window, use @kbd{C-x o} (@code{other-window}). ! 5916: That is an @kbd{o}, for `other', not a zero. When there are more than two ! 5917: windows, this command moves through all the windows in a cyclic order, ! 5918: generally top to bottom and left to right. From the rightmost and ! 5919: bottommost window, it goes back to the one at the upper left corner. A ! 5920: numeric argument means to move several steps in the cyclic order of ! 5921: windows. A negative argument moves around the cycle in the opposite order. ! 5922: When the minibuffer is active, the minibuffer is the last window in the ! 5923: cycle; you can switch from the minibuffer window to one of the other ! 5924: windows, and later switch back and finish supplying the minibuffer argument ! 5925: that is requested. @xref{Minibuffer Edit}. ! 5926: ! 5927: @kindex C-M-v ! 5928: @findex scroll-other-window ! 5929: The usual scrolling commands (@pxref{Display}) apply to the selected ! 5930: window only, but there is one command to scroll the next window. ! 5931: @kbd{C-M-v} (@code{scroll-other-window}) scrolls the window that @kbd{C-x o} ! 5932: would select. It takes arguments, positive and negative, like @kbd{C-v}. ! 5933: ! 5934: @findex compare-windows ! 5935: The command @kbd{M-x compare-windows} compares the text in the current ! 5936: window with that in the next window. Comparison starts at point in each ! 5937: window. Point moves forward in each window, a character at a time in each ! 5938: window, until the next characters in the two windows are different. Then ! 5939: the command is finished. ! 5940: ! 5941: @node Pop Up Window, Change Window, Other Window, Windows ! 5942: @section Displaying in Another Window ! 5943: ! 5944: @kindex C-x 4 ! 5945: @kbd{C-x 4} is a prefix key for commands that select another window ! 5946: (splitting the window if there is only one) and select a buffer in that ! 5947: window. Different @kbd{C-x 4} commands have different ways of finding the ! 5948: buffer to select. ! 5949: ! 5950: @findex switch-to-buffer-other-window ! 5951: @findex find-file-other-window ! 5952: @findex find-tag-other-window ! 5953: @findex dired-other-window ! 5954: @findex mail-other-window ! 5955: @table @kbd ! 5956: @item C-x 4 b @var{bufname} @key{RET} ! 5957: Select buffer @var{bufname} in another window. This runs @* ! 5958: @code{switch-to-buffer-other-window}. ! 5959: @item C-x 4 f @var{filename} @key{RET} ! 5960: Visit file @var{filename} and select its buffer in another window. This ! 5961: runs @code{find-file-other-window}. @xref{Visiting}. ! 5962: @item C-x 4 d @var{directory} @key{RET} ! 5963: Select a Dired buffer for directory @var{directory} in another window. ! 5964: This runs @code{dired-other-window}. @xref{Dired}. ! 5965: @item C-x 4 m ! 5966: Start composing a mail message in another window. This runs ! 5967: @code{mail-other-window}, and its same-window version is @kbd{C-x m} ! 5968: (@pxref{Sending Mail}). ! 5969: @item C-x 4 . ! 5970: Find a tag in the current tag table in another window. This runs ! 5971: @code{find-tag-other-window}, the multiple-window variant of @kbd{M-.} ! 5972: (@pxref{Tags}). ! 5973: @end table ! 5974: ! 5975: @node Change Window,, Pop Up Window, Windows ! 5976: @section Deleting and Rearranging Windows ! 5977: ! 5978: @table @kbd ! 5979: @item C-x 0 ! 5980: Get rid of the selected window (@code{kill-window}). That is a zero. ! 5981: @item C-x 1 ! 5982: Get rid of all windows except the selected one (@code{delete-other-windows}). ! 5983: @item C-x ^ ! 5984: Make the selected window taller, at the expense of the other(s) ! 5985: (@code{enlarge-window}). ! 5986: @item C-x @} ! 5987: Make the selected window wider (@code{enlarge-window-horizontally}). ! 5988: @end table ! 5989: ! 5990: @kindex C-x 0 ! 5991: @findex delete-window ! 5992: To delete a window, type @kbd{C-x 0} (@code{delete-window}). (That is a ! 5993: zero.) The space occupied by the deleted window is distributed among the ! 5994: other active windows (but not the minibuffer window, even if that is active ! 5995: at the time). Once a window is deleted, its attributes are forgotten; ! 5996: there is no automatic way to make another window of the same shape or ! 5997: showing the same buffer. But the buffer continues to exist, and you can ! 5998: select it in any window with @kbd{C-x b}. ! 5999: ! 6000: @kindex C-x 1 ! 6001: @findex delete-other-windows ! 6002: @kbd{C-x 1} (@code{delete-other-windows}) is more powerful than @kbd{C-x 0}; ! 6003: it deletes all the windows except the selected one (and the minibuffer); ! 6004: the selected window expands to use the whole screen except for the echo ! 6005: area. ! 6006: ! 6007: @kindex C-x ^ ! 6008: @findex enlarge-window ! 6009: @kindex C-x @} ! 6010: @findex enlarge-window-horizontally ! 6011: @vindex window-min-height ! 6012: @vindex window-min-width ! 6013: To readjust the division of space among existing windows, use @kbd{C-x ^} ! 6014: (@code{enlarge-window}). It makes the currently selected window get one ! 6015: line bigger, or as many lines as is specified with a numeric argument. ! 6016: With a negative argument, it makes the selected window smaller. @kbd{C-x ! 6017: @}} (@code{enlarge-window-horizontally}) makes the selected window wider ! 6018: by the specified number of columns. The extra screen space given to a ! 6019: window comes from one of its neighbors, if that is possible; otherwise, all ! 6020: the competing windows are shrunk in the same proportion. If this makes any ! 6021: windows too small, those windows are deleted and their space is divided up. ! 6022: The minimum size is specified by the variables @code{window-min-height} and ! 6023: @code{window-min-width}. ! 6024: ! 6025: @node Major Modes, Indentation, Windows, Top ! 6026: @chapter Major Modes ! 6027: @cindex major modes ! 6028: @kindex TAB ! 6029: @kindex DEL ! 6030: @kindex LFD ! 6031: ! 6032: Emacs has many different @dfn{major modes}, each of which customizes ! 6033: Emacs for editing text of a particular sort. The major modes are mutually ! 6034: exclusive, and each buffer has one major mode at any time. The mode line ! 6035: normally contains the name of the current major mode, in parentheses. ! 6036: @xref{Mode Line}. ! 6037: ! 6038: The least specialized major mode is called @dfn{Fundamental mode}. This ! 6039: mode has no mode-specific redefinitions or variable settings, so that each ! 6040: Emacs command behaves in its most general manner, and each option is in its ! 6041: default state. For editing any specific type of text, such as Lisp code or ! 6042: English text, you should switch to the appropriate major mode, such as Lisp ! 6043: mode or Text mode. ! 6044: ! 6045: Selecting a major mode changes the meanings of a few keys to become more ! 6046: specifically adapted to the language being edited. The ones which are ! 6047: changed frequently are @key{TAB}, @key{DEL}, and @key{LFD}. In addition, ! 6048: the commands which handle comments use the mode to determine how comments ! 6049: are to be delimited. Many major modes redefine the syntactical properties ! 6050: of characters appearing in the buffer. @xref{Syntax}. ! 6051: ! 6052: The major modes fall into three major groups. Lisp mode (which has ! 6053: several variants), C mode and Muddle mode are for specific programming ! 6054: languages. Text mode, Nroff mode, @TeX{} mode and Outline mode are for ! 6055: editing English text. The remaining major modes are not intended for use ! 6056: on users' files; they are used in buffers created for specific purposes by ! 6057: Emacs, such as Dired mode for buffers made by Dired (@pxref{Dired}), and ! 6058: Mail mode for buffers made by @kbd{C-x m} (@pxref{Sending Mail}), and Shell ! 6059: mode for buffers used for communicating with an inferior shell process ! 6060: (@pxref{Interactive Shell}). ! 6061: ! 6062: Most programming language major modes specify that only blank lines ! 6063: separate paragraphs. This is so that the paragraph commands remain useful. ! 6064: @xref{Paragraphs}. They also cause Auto Fill mode to use the definition of ! 6065: @key{TAB} to indent the new lines it creates. This is because most lines ! 6066: in a program are usually indented. @xref{Indentation}. ! 6067: ! 6068: @menu ! 6069: * Choosing Modes:: How major modes are specified or chosen. ! 6070: @end menu ! 6071: ! 6072: @node Choosing Modes,,Major Modes,Major Modes ! 6073: @section How Major Modes are Chosen ! 6074: ! 6075: You can select a major mode explicitly for the current buffer, but ! 6076: most of the time Emacs determines which mode to use based on the file ! 6077: name or some text in the file. ! 6078: ! 6079: Explicit selection of a new major mode is done with a @kbd{M-x} command. ! 6080: From the name of a major mode, add @code{-mode} to get the name of a ! 6081: command to select that mode. Thus, you can enter Lisp mode by executing ! 6082: @kbd{M-x lisp-mode}. ! 6083: ! 6084: @vindex auto-mode-alist ! 6085: When you visit a file, Emacs usually chooses the right major mode based ! 6086: on the file's name. For example, files whose names end in @code{.c} are ! 6087: edited in C mode. The correspondence between file names and major mode is ! 6088: controlled by the variable @code{auto-mode-alist}. Its value is a list in ! 6089: which each element has the form ! 6090: ! 6091: @example ! 6092: (@var{regexp} . @var{mode-function}) ! 6093: @end example ! 6094: ! 6095: @noindent ! 6096: For example, one element normally found in the list has the form ! 6097: @code{(@t{"\\.c$"} . c-mode)}, and it is responsible for selecting C mode ! 6098: for files whose names end in @file{.c}. (Note that @samp{\\} is needed in ! 6099: Lisp syntax to include a @samp{\} in the string, which is needed to ! 6100: suppress the special meaning of @samp{.} in regexps.) The only practical ! 6101: way to change this variable is with Lisp code. ! 6102: ! 6103: You can specify which major mode should be used for editing a certain ! 6104: file by a special sort of text in the first nonblank line of the file. The ! 6105: mode name should appear in this line both preceded and followed by ! 6106: @samp{-*-}. Other text may appear on the line as well. For example, ! 6107: ! 6108: @example ! 6109: ;-*-Lisp-*- ! 6110: @end example ! 6111: ! 6112: @noindent ! 6113: tells Emacs to use Lisp mode. Note how the semicolon is used to make Lisp ! 6114: treat this line as a comment. Such an explicit specification overrides any ! 6115: defaulting based on the file name. ! 6116: ! 6117: Another format of mode specification is ! 6118: ! 6119: @example ! 6120: -*-Mode: @var{modename};-*- ! 6121: @end example ! 6122: ! 6123: @noindent ! 6124: which allows other things besides the major mode name to be specified. ! 6125: However, Emacs does not look for anything except the mode name. ! 6126: ! 6127: The major mode can also be specified in a local variables list. ! 6128: @xref{File Variables}. ! 6129: ! 6130: @vindex default-major-mode ! 6131: When a file is visited that does not specify a major mode to use, or when ! 6132: a new buffer is created with @kbd{C-x b}, the major mode used is that ! 6133: specified by the variable @code{default-major-mode}. Normally this value ! 6134: is the symbol @code{fundamental-mode}, which specifies Fundamental mode. ! 6135: If @code{default-major-mode} is @code{nil}, the major mode is taken from ! 6136: the previously selected buffer. ! 6137: ! 6138: @node Indentation, Text, Major Modes, Top ! 6139: @chapter Indentation ! 6140: @cindex indentation ! 6141: ! 6142: @c WideCommands ! 6143: @table @kbd ! 6144: @item @key{TAB} ! 6145: Indent current line ``appropriately'' in a mode-dependent fashion. ! 6146: @item @key{LFD} ! 6147: Perform @key{RET} followed by @key{TAB} (@code{newline-and-indent}). ! 6148: @item M-^ ! 6149: Merge two lines (@code{delete-indentation}). This would cancel out ! 6150: the effect of @key{LFD}. ! 6151: @item C-M-o ! 6152: Split line at point; text on the line after point becomes a new line ! 6153: indented to the same column that it now starts in (@code{split-line}). ! 6154: @item M-m ! 6155: Move (forward or back) to the first nonblank character on the current ! 6156: line (@code{back-to-indentation}). ! 6157: @item C-M-\ ! 6158: Indent several lines to same column (@code{indent-region}). ! 6159: @item C-x @key{TAB} ! 6160: Shift block of lines rigidly right or left (@code{indent-rigidly}). ! 6161: @item M-i ! 6162: Indent from point to the next prespecified tab stop column ! 6163: (@code{tab-to-tab-stop}). ! 6164: @item M-x indent-relative ! 6165: Indent from point to under an indentation point in the previous line. ! 6166: @end table ! 6167: ! 6168: @kindex TAB ! 6169: @cindex indentation ! 6170: Most programming languages have some indentation convention. For Lisp ! 6171: code, lines are indented according to their nesting in parentheses. The ! 6172: same general idea is used for C code, though many details are different. ! 6173: ! 6174: Whatever the language, to indent a line, use the @key{TAB} command. Each ! 6175: major mode defines this command to perform the sort of indentation ! 6176: appropriate for the particular language. In Lisp mode, @key{TAB} aligns ! 6177: the line according to its depth in parentheses. No matter where in the ! 6178: line you are when you type @key{TAB}, it aligns the line as a whole. In C ! 6179: mode, @key{TAB} implements a subtle and sophisticated indentation style that ! 6180: knows about many aspects of C syntax. ! 6181: ! 6182: @kindex TAB ! 6183: In Text mode, @key{TAB} runs the command @code{tab-to-tab-stop}, which ! 6184: indents to the next tab stop column. You can set the tab stops with ! 6185: @kbd{M-x edit-tab-stops}. ! 6186: ! 6187: @menu ! 6188: * Indentation Commands:: Various commands and techniques for indentation. ! 6189: * Tab Stops:: You can set arbitrary "tab stops" and then ! 6190: indent to the next tab stop when you want to. ! 6191: * Just Spaces:: You can request indentation using just spaces. ! 6192: @end menu ! 6193: ! 6194: @node Indentation Commands, Tab Stops, Indentation, Indentation ! 6195: @section Indentation Commands and Techniques ! 6196: @c ??? Explain what Emacs has instead of space-indent-flag. ! 6197: ! 6198: If you just want to insert a tab character in the buffer, you can type ! 6199: @kbd{C-q @key{TAB}}. ! 6200: ! 6201: @kindex M-m ! 6202: @findex back-to-indentation ! 6203: To move over the indentation on a line, do @kbd{Meta-m} ! 6204: (@code{back-to-indentation}). This command, given anywhere on a line, ! 6205: positions point at the first nonblank character on the line. ! 6206: ! 6207: To insert an indented line before the current line, do @kbd{C-a C-o ! 6208: @key{TAB}}. To make an indented line after the current line, use @kbd{C-e ! 6209: @key{LFD}}. ! 6210: ! 6211: @kindex C-M-o ! 6212: @findex split-line ! 6213: @kbd{C-M-o} (@code{split-line}) moves the text from point to the end of ! 6214: the line vertically down, so that the current line becomes two lines. ! 6215: @kbd{C-M-o} first moves point forward over any spaces and tabs. Then it ! 6216: inserts after point a newline and enough indentation to reach the same ! 6217: column point is on. Point remains before the inserted newline; in this ! 6218: regard, @kbd{C-M-o} resembles @kbd{C-o}. ! 6219: ! 6220: @kindex M-\ ! 6221: @kindex M-^ ! 6222: @findex delete-horizontal-space ! 6223: @findex delete-indentation ! 6224: To join two lines cleanly, use the @kbd{Meta-^} (@code{delete-indentation}) ! 6225: command to delete the indentation at the front of the current line, and the ! 6226: line boundary as well. They are replaced by a single space, or by no space ! 6227: if at the beginning of a line or before a @samp{)} or after a @samp{(}. To ! 6228: delete just the indentation of a line, go to the beginning of the line and ! 6229: use @kbd{Meta-\} (@code{delete-horizontal-space}), which deletes all spaces ! 6230: and tabs around the cursor. ! 6231: ! 6232: @kindex C-M-\ ! 6233: @kindex C-x TAB ! 6234: @findex indent-region ! 6235: @findex indent-rigidly ! 6236: There are also commands for changing the indentation of several lines at ! 6237: once. @kbd{Control-Meta-\} (@code{indent-region}) gives each line which ! 6238: begins in the region the ``usual'' indentation by invoking @key{TAB} at the ! 6239: beginning of the line. A numeric argument specifies the column to indent ! 6240: to, and each line is shifted left or right so that its first nonblank ! 6241: character appears in that column. @kbd{C-x @key{TAB}} ! 6242: (@code{indent-rigidly}) moves all of the lines in the region right by its ! 6243: argument (left, for negative arguments). The whole group of lines moves ! 6244: rigidly sideways, which is how the command gets its name.@refill ! 6245: ! 6246: @findex indent-relative ! 6247: @kbd{M-x indent-relative} indents at point based on the previous line ! 6248: (actually, the last nonempty line.) It inserts whitespace at point, moving ! 6249: point, until it is underneath an indentation point in the previous line. ! 6250: An indentation point is the end of a sequence of whitespace or the end of ! 6251: the line. If point is farther right than any indentation point in the ! 6252: previous line, the whitespace before point is deleted and the first ! 6253: indentation point then applicable is used. If no indentation point is ! 6254: applicable even then, @code{tab-to-tab-stop} is run (see next section). ! 6255: ! 6256: @code{indent-relative} is the definition of @key{TAB} in Indented Text ! 6257: mode. @xref{Text}. ! 6258: ! 6259: @node Tab Stops, Just Spaces, Indentation Commands, Indentation ! 6260: @section Tab Stops ! 6261: ! 6262: @kindex M-i ! 6263: @findex tab-to-tab-stop ! 6264: For typing in tables, you can use Text mode's definition of @key{TAB}, ! 6265: @code{tab-to-tab-stop}. This command inserts indentation before point, ! 6266: enough to reach the next tab stop column. If you are not in Text mode, ! 6267: this function can be found on @kbd{M-i} anyway. ! 6268: ! 6269: @findex edit-tab-stops ! 6270: @findex edit-tab-stops-note-changes ! 6271: @kindex C-c C-c (Edit Tab Stops) ! 6272: @vindex tab-stop-list ! 6273: The tab stops used by @kbd{M-i} can be set arbitrarily by the user. ! 6274: They are stored in a variable called @code{tab-stop-list}, as a list of ! 6275: column-numbers in increasing order. ! 6276: ! 6277: The convenient way to set the tab stops is using @kbd{M-x edit-tab-stops}, ! 6278: which creates and selects a buffer containing a description of the tab stop ! 6279: settings. You can edit this buffer to specify different tab stops, and ! 6280: then type @kbd{C-c C-c} to make those new tab stops take effect. In the ! 6281: tab stop buffer, @kbd{C-c C-c} runs the function ! 6282: @code{edit-tab-stops-note-changes} rather than its usual definition ! 6283: @code{save-buffer}. @code{edit-tab-stops} records which buffer was current ! 6284: when you invoked it, and stores the tab stops back in that buffer; normally ! 6285: all buffers share the same tab stops and changing them in one buffer ! 6286: affects all, but if you happen to make @code{tab-stop-list} local in one ! 6287: buffer then @code{edit-tab-stops} in that buffer will edit the local ! 6288: settings. ! 6289: ! 6290: Here is what the text representing the tab stops looks like for ordinary ! 6291: tab stops every eight columns. ! 6292: ! 6293: @example ! 6294: : : : : : : ! 6295: 0 1 2 3 4 ! 6296: 0123456789012345678901234567890123456789012345678 ! 6297: To install changes, type C-c C-c ! 6298: @end example ! 6299: ! 6300: The first line contains a colon at each tab stop. The remaining lines ! 6301: are present just to help you see where the colons are and know what to do. ! 6302: ! 6303: Note that the tab stops that control @code{tab-to-tab-stop} have nothing ! 6304: to do with displaying tab characters in the buffer. @xref{Display Vars}, ! 6305: for more information on that. ! 6306: ! 6307: @node Just Spaces,, Tab Stops, Indentation ! 6308: @section Tabs vs. Spaces ! 6309: ! 6310: @vindex indent-tabs-mode ! 6311: Emacs normally uses both tabs and spaces to indent lines. If you prefer, ! 6312: all indentation can be made from spaces only. To request this, set ! 6313: @code{indent-tabs-mode} to @code{nil}. This is a per-buffer variable; ! 6314: altering the variable affects only the current buffer, but there is a ! 6315: default value which you can change as well. @xref{Locals}. ! 6316: ! 6317: @findex tabify ! 6318: @findex untabify ! 6319: There are also commands to convert tabs to spaces or vice versa, always ! 6320: preserving the columns of all nonblank text. @kbd{M-x tabify} scans the ! 6321: region for sequences of spaces, and converts sequences of at least three ! 6322: spaces to tabs if that can be done without changing indentation. @kbd{M-x ! 6323: untabify} changes all tabs in the region to appropriate numbers of spaces. ! 6324: ! 6325: @node Text, Programs, Indentation, Top ! 6326: @chapter Commands for Human Languages ! 6327: @cindex text ! 6328: ! 6329: The term @dfn{text} has two widespread meanings in our area of the ! 6330: computer field. One is data that is a sequence of characters. Any file ! 6331: that you edit with Emacs is text, in this sense of the word. The other ! 6332: meaning is more restrictive: a sequence of characters in a human language ! 6333: for humans to read (possibly after processing by a text formatter), as ! 6334: opposed to a program or commands for a program. ! 6335: ! 6336: Human languages have syntactic/stylistic conventions that can be ! 6337: supported or used to advantage by editor commands: conventions involving ! 6338: words, sentences, paragraphs, and capital letters. This chapter describes ! 6339: Emacs commands for all of these things. There are also commands for ! 6340: @dfn{filling}, or rearranging paragraphs into lines of approximately equal ! 6341: length. The commands for moving over and killing words, sentences ! 6342: and paragraphs, while intended primarily for editing text, are also often ! 6343: useful for editing programs. ! 6344: ! 6345: Emacs has several major modes for editing human language text. ! 6346: If the file contains text pure and simple, use Text mode, which customizes ! 6347: Emacs in small ways for the syntactic conventions of text. For text which ! 6348: contains embedded commands for text formatters, Emacs has other major modes, ! 6349: each for a particular text formatter. Thus, for input to @TeX{}, you would ! 6350: use @TeX{} mode; for input to nroff, Nroff mode. ! 6351: ! 6352: @menu ! 6353: * Text Mode:: The major modes for editing text files. ! 6354: * Nroff Mode:: The major mode for editing input to the formatter nroff. ! 6355: * TeX Mode:: The major modes for editing input to the formatter TeX. ! 6356: * Outline Mode::The major mode for editing outlines. ! 6357: * Words:: Moving over and killing words. ! 6358: * Sentences:: Moving over and killing sentences. ! 6359: * Paragraphs:: Moving over paragraphs. ! 6360: * Pages:: Moving over pages. ! 6361: * Filling:: Filling or justifying text ! 6362: * Case:: Changing the case of text ! 6363: @end menu ! 6364: ! 6365: @node Text Mode, Words, Text, Text ! 6366: @section Text Mode ! 6367: ! 6368: @findex tab-to-tab-stop ! 6369: @findex edit-tab-stops ! 6370: @cindex Text mode ! 6371: @kindex TAB ! 6372: @findex text-mode ! 6373: Editing files of text in a human language ought to be done using Text ! 6374: mode rather than Lisp or Fundamental mode. Invoke @kbd{M-x text-mode} to ! 6375: enter Text mode. In Text mode, @key{TAB} runs the function ! 6376: @code{tab-to-tab-stop}, which allows you to use arbitrary tab stops set ! 6377: with @kbd{M-x edit-tab-stops} (@pxref{Tab Stops}). Features concerned with ! 6378: comments in programs are turned off except when explicitly invoked. The ! 6379: syntax table is changed so that periods are not considered part of a word, ! 6380: while apostrophes, backspaces and underlines are. ! 6381: ! 6382: @findex indented-text-mode ! 6383: A similar variant mode is Indented Text mode, intended for editing text ! 6384: in which most lines are indented. This mode defines @key{TAB} to run ! 6385: @code{indent-relative} (@pxref{Indentation}), and makes Auto Fill indent ! 6386: the lines it creates. The result is that normally a line made by Auto ! 6387: Filling, or by @key{LFD}, is indented just like the previous line. Use ! 6388: @kbd{M-x indented-text-mode} to select this mode. ! 6389: ! 6390: @vindex text-mode-hook ! 6391: Entering Text mode or Indented Text mode calls with no arguments the ! 6392: value of the variable @code{text-mode-hook}, if that value exists and is ! 6393: not @code{nil}. This value is also called when modes related to Text mode ! 6394: are entered; this includes Nroff mode, @TeX{} mode, Outline mode and Mail ! 6395: mode. Your hook can look at the value of @code{major-mode} to see which of ! 6396: these modes is actually being entered. ! 6397: ! 6398: @menu ! 6399: Two modes similar to Text mode are of use for editing text that is to ! 6400: be passed through a text formatter before achieving the form in which ! 6401: humans are to read it. ! 6402: ! 6403: * Nroff Mode:: The major mode for editing input to the formatter nroff. ! 6404: * TeX Mode:: The major modes for editing input to the formatter TeX. ! 6405: ! 6406: Another similar mode is used for editing outlines. It allows you ! 6407: to view the text at various levels of detail. You can view either ! 6408: the outline headings alone or both headings and text; you can also ! 6409: hide some of the headings at lower levels from view to make the high ! 6410: level structure more visible. ! 6411: ! 6412: * Outline Mode::The major mode for editing outlines. ! 6413: @end menu ! 6414: ! 6415: @node Nroff Mode, TeX Mode, Text Mode, Text Mode ! 6416: @subsection Nroff Mode ! 6417: ! 6418: @cindex nroff ! 6419: @findex nroff-mode ! 6420: Nroff mode is a mode like Text mode but modified to handle nroff commands ! 6421: present in the text. Invoke @kbd{M-x nroff-mode} to enter this mode. It ! 6422: differs from Text mode in only a few ways. All nroff command lines are ! 6423: considered paragraph separators, so that filling will never garble the ! 6424: nroff commands. Pages are separated by @samp{.bp} commands. Comments ! 6425: start with backslash-doublequote. Also, three special commands are ! 6426: provided that are not in Text mode: ! 6427: ! 6428: @findex forward-text-line ! 6429: @findex backward-text-line ! 6430: @findex count-text-lines ! 6431: @kindex M-n ! 6432: @kindex M-p ! 6433: @kindex M-? ! 6434: @table @kbd ! 6435: @item M-n ! 6436: Move to the beginning of the next line that isn't an nroff command ! 6437: (@code{forward-text-line}). An argument is a repeat count. ! 6438: @item M-p ! 6439: Like @kbd{M-n} but move up (@code{backward-text-line}). ! 6440: @item M-? ! 6441: Prints in the echo area the number of text lines (lines that are not ! 6442: nroff commands) in the region (@code{count-text-lines}). ! 6443: @end table ! 6444: ! 6445: @findex electric-nroff-mode ! 6446: The other feature of Nroff mode is that you can turn on Electric ! 6447: Nroff newline mode. This is a minor mode that you can turn on or off ! 6448: with @kbd{M-x electric-nroff-mode} (@pxref{Minor Modes}). When the ! 6449: mode is on, each time you use @key{RET} to end a line that contains ! 6450: an nroff command that opens a kind of grouping, the matching ! 6451: nroff command to close that grouping is automatically inserted on ! 6452: the following line. For example, if you are at the beginning of ! 6453: a line and type @kbd{.@: ( b @key{RET}}, the matching command ! 6454: @samp{.)b} will be inserted on a new line following point. ! 6455: ! 6456: @vindex nroff-mode-hook ! 6457: Entering Nroff mode calls with no arguments the value of the variable ! 6458: @code{text-mode-hook}, if that value exists and is not @code{nil}; then it ! 6459: does the same with the variable @code{nroff-mode-hook}. ! 6460: ! 6461: @node TeX Mode, Outline Mode, Nroff Mode, Text Mode ! 6462: @subsection @TeX{} Mode ! 6463: @cindex TeX ! 6464: @cindex LaTeX ! 6465: @findex TeX-mode ! 6466: @findex tex-mode ! 6467: @findex plain-tex-mode ! 6468: @findex LaTeX-mode ! 6469: @findex plain-TeX-mode ! 6470: @findex latex-mode ! 6471: ! 6472: @TeX{} is a powerful text formatter written by Donald Knuth; it is also ! 6473: free, like GNU Emacs. La@TeX{} is a simplified input format for @TeX{}, ! 6474: implemented by @TeX{} macros. It comes with @TeX{}.@refill ! 6475: ! 6476: Emacs has a special @TeX{} mode for editing @TeX{} input files. ! 6477: It provides facilities for checking the balance of delimiters and for ! 6478: invoking @TeX{} on all or part of the file. ! 6479: ! 6480: @TeX{} mode has two variants, Plain @TeX{} mode and La@TeX{} mode ! 6481: (actually two distinct major modes which differ only slightly). They are ! 6482: designed for editing the two different input formats. The command @kbd{M-x ! 6483: tex-mode} looks at the contents of the buffer to determine whether the ! 6484: contents appear to be La@TeX{} input or not; it then selects the ! 6485: appropriate mode. If it can't tell which is right (e.g., the buffer is ! 6486: empty), the variable @code{TeX-default-mode} controls which mode is used. ! 6487: ! 6488: The commands @kbd{M-x plain-tex-mode} and @kbd{M-x latex-mode} explicitly ! 6489: select the two variants of @TeX{} mode. Use these commands when @kbd{M-x ! 6490: tex-mode} does not guess right.@refill ! 6491: ! 6492: @menu ! 6493: * Editing: TeX Editing. Special commands for editing in TeX mode. ! 6494: * Printing: TeX Print. Commands for printing part of a file with TeX. ! 6495: @end menu ! 6496: ! 6497: @TeX{} for Unix systems can be obtained from the University of Washington ! 6498: for a distribution fee. ! 6499: ! 6500: To order a full distribution, send $140.00 for a 1/2 inch ! 6501: 9-track tape, $165.00 for two 4-track 1/4 inch cartridge tapes ! 6502: (foreign sites $150.00, for 1/2 inch, $175.00 for 1/4 inch, to cover ! 6503: the extra postage) payable to the University of Washington to: ! 6504: ! 6505: @display ! 6506: The Director ! 6507: Northwest Computer Support Group, DW-10 ! 6508: University of Washington ! 6509: Seattle, Washington 98195 ! 6510: @end display ! 6511: ! 6512: @noindent ! 6513: Purchase orders are acceptable, but there is an extra charge of ! 6514: $10.00, to pay for processing charges. (Total of $150 for domestic ! 6515: sites, $175 for foreign sites). ! 6516: ! 6517: The normal distribution is a tar tape, blocked 20, 1600 bpi, on an ! 6518: industry standard 2400 foot half-inch reel. The physical format for ! 6519: the 1/4 inch streamer cartridges uses QIC-11, 8000 bpi, 4-track ! 6520: serpentine recording for the SUN. Also, SystemV tapes can be written ! 6521: in cpio format, blocked 5120 bytes, ASCII headers. ! 6522: ! 6523: @node TeX Editing,TeX Print,TeX Mode,TeX Mode ! 6524: @subsubsection @TeX{} Editing Commands ! 6525: ! 6526: Here are the special commands provided in @TeX{} mode for editing the ! 6527: text of the file. ! 6528: ! 6529: @table @kbd ! 6530: @item " ! 6531: Insert, according to context, either @samp{@`@`} or @samp{"} or ! 6532: @samp{@'@'} (@code{TeX-insert-quote}). ! 6533: @item @key{LFD} ! 6534: Insert a paragraph break (two newlines) and check the previous ! 6535: paragraph for unbalanced braces or dollar signs ! 6536: (@code{TeX-terminate-paragraph}). ! 6537: @item M-x validate-TeX-buffer ! 6538: Check each paragraph in the buffer for unbalanced braces or dollar signs. ! 6539: @item M-@{ ! 6540: Insert @samp{@{@}} and position point between them (@code{TeX-insert-braces}). ! 6541: @item M-@} ! 6542: Move forward past the next unmatched close brace (@code{up-list}). ! 6543: @item C-c C-f ! 6544: Close a block for La@TeX{} (@code{TeX-close-LaTeX-block}). ! 6545: @end table ! 6546: ! 6547: @findex TeX-insert-quote ! 6548: @kindex " (TeX mode) ! 6549: In @TeX{}, the character @samp{"} is not normally used; one uses @samp{``} ! 6550: to start a quotation and @samp{''} to end one. @TeX{} mode defines the key ! 6551: @kbd{"} to insert @samp{``} after whitespace or an open brace, @samp{"} ! 6552: after a backslash, or @samp{''} otherwise. This is done by the command ! 6553: @code{TeX-insert-quote}. If you need the character @samp{"} itself in ! 6554: unusual contexts, use @kbd{C-q} to insert it. Also, @kbd{"} with a ! 6555: numeric argument always inserts that number of @samp{"} characters. ! 6556: ! 6557: In @TeX{} mode, @samp{$} has a special syntax code which attempts to ! 6558: understand the way @TeX{} math mode delimiters match. When you insert a ! 6559: @samp{$} that is meant to exit math mode, the position of the matching ! 6560: @samp{$} that entered math mode is displayed for a second. This is the ! 6561: same feature that displays the open brace that matches a close brace that ! 6562: is inserted. However, there is no way to tell whether a @samp{$} enters ! 6563: math mode or leaves it; so when you insert a @samp{$} that enters math ! 6564: mode, the previous @samp{$} position is shown as if it were a match, even ! 6565: though they are actually unrelated. ! 6566: ! 6567: @findex TeX-insert-braces ! 6568: @kindex M-@{ (TeX mode) ! 6569: @findex up-list ! 6570: @kindex M-@} (TeX mode) ! 6571: If you prefer to keep braces balanced at all times, you can use @kbd{M-@{} ! 6572: (@code{TeX-insert-braces}) to insert a pair of braces. It leaves point ! 6573: between the two braces so you can insert the text that belongs inside. ! 6574: Afterward, use the command @kbd{M-@}} (@code{up-list}) to move forward ! 6575: past the close brace. ! 6576: ! 6577: @findex validate-TeX-buffer ! 6578: @findex TeX-terminate-paragraph ! 6579: @kindex LFD (TeX mode) ! 6580: There are two commands for checking the matching of braces. @key{LFD} ! 6581: (@code{TeX-terminate-paragraph}) checks the paragraph before point, and ! 6582: inserts two newlines to start a new paragraph. It prints a message in the ! 6583: echo area if any mismatch is found. @kbd{M-x validate-TeX-buffer} checks ! 6584: the entire buffer, paragraph by paragraph. When it finds a paragraph that ! 6585: contains a mismatch, it displays point at the beginning of the paragraph ! 6586: for a few seconds and pushes a mark at that spot. Scanning continues ! 6587: until the whole buffer has been checked or until you type another key. ! 6588: The positions of the last several paragraphs with mismatches can be ! 6589: found in the mark ring (@pxref{Mark Ring}). ! 6590: ! 6591: Note that square brackets and parentheses are matched in @TeX{} mode, not ! 6592: just braces. This is wrong for the purpose of checking @TeX{} syntax. ! 6593: However, parentheses and square brackets are likely to be used in text as ! 6594: matching delimiters and it is useful for the various motion commands and ! 6595: automatic match display to work with them. ! 6596: ! 6597: @findex TeX-close-LaTeX-block ! 6598: @kindex C-c C-f (LaTeX mode) ! 6599: In La@TeX{} input, @samp{\begin} and @samp{\end} commands must balance. ! 6600: After you insert a @samp{\begin}, use @kbd{C-c C-f} ! 6601: (@code{TeX-close-LaTeX-block}) to insert automatically a matching ! 6602: @samp{\end} (on a new line following the @samp{\begin}). A blank line is ! 6603: inserted between the two, and point is left there.@refill ! 6604: ! 6605: @node TeX Print,,TeX Editing,TeX Mode ! 6606: @subsubsection @TeX{} Printing Commands ! 6607: ! 6608: You can invoke @TeX{} as an inferior of Emacs on either the entire ! 6609: contents of the buffer or just a region at a time. Running @TeX{} in ! 6610: this way on just one chapter is a good way to see what your changes ! 6611: look like without taking the time to format the entire file. ! 6612: ! 6613: @table @kbd ! 6614: @item C-c C-r ! 6615: Invoke @TeX{} on the current region, plus the buffer's header ! 6616: (@code{TeX-region}). ! 6617: @item C-c C-b ! 6618: Invoke @TeX{} on the entire current buffer (@code{TeX-buffer}). ! 6619: @item C-c C-l ! 6620: Recenter the window showing output from the inferior @TeX{} so that ! 6621: the last line can be seen (@code{TeX-recenter-output-buffer}). ! 6622: @item C-c C-k ! 6623: Kill the inferior @TeX{} (@code{TeX-kill-job}). ! 6624: @item C-c C-p ! 6625: Print the output from the last @kbd{C-c C-r} or @kbd{C-c C-b} command ! 6626: (@code{TeX-print}). ! 6627: @item C-c C-q ! 6628: Show the printer queue (@code{TeX-show-print-queue}). ! 6629: @end table ! 6630: ! 6631: @findex TeX-buffer ! 6632: @kindex C-c C-b (TeX mode) ! 6633: @findex TeX-print ! 6634: @kindex C-c C-p (TeX mode) ! 6635: @findex TeX-show-print-queue ! 6636: @kindex C-c C-q (TeX mode) ! 6637: You can pass the current buffer through an inferior @TeX{} by means of ! 6638: @kbd{C-c C-b} (@code{TeX-buffer}). The formatted output appears in a file ! 6639: in @file{/tmp}; to print it, type @kbd{C-c C-p} (@code{TeX-print}). ! 6640: Afterward use @kbd{C-c C-q} (@code{TeX-show-print-queue}) to view the ! 6641: progress of your output towards being printed. ! 6642: ! 6643: @findex TeX-kill-job ! 6644: @kindex C-c C-k (TeX mode) ! 6645: @findex TeX-recenter-output-buffer ! 6646: @kindex C-c C-l (TeX mode) ! 6647: The console output from @TeX{}, including any error messages, appear in a ! 6648: buffer called @samp{*TeX-shell*}. If @TeX{} gets an error, you can switch ! 6649: to this buffer and feed it input (this works as in Shell mode; ! 6650: @pxref{Interactive Shell}). Without switching to this buffer you can scroll ! 6651: it so that its last line is visible by typing @kbd{C-c C-l}. ! 6652: ! 6653: Type @kbd{C-c C-k} (@code{TeX-kill-job}) to kill the @TeX{} process if ! 6654: you see that its output is no longer useful. Using @kbd{C-c C-b} or ! 6655: @kbd{C-c C-r} also kills any @TeX{} process still running.@refill ! 6656: ! 6657: @findex TeX-region ! 6658: @kindex C-c C-r (TeX mode) ! 6659: You can also pass an arbitrary region through an inferior @TeX{} by typing ! 6660: @kbd{C-c C-r} (@code{TeX-region}). This is tricky, however, because most files ! 6661: of @TeX{} input contain commands at the beginning to set parameters and ! 6662: define macros, without which no later part of the file will format ! 6663: correctly. To solve this problem, @kbd{C-c C-r} allows you to designate a ! 6664: part of the file as containing essential commands; it is included before ! 6665: the specified region as part of the input to @TeX{}. The designated part ! 6666: of the file is called the @dfn{header}. ! 6667: ! 6668: @cindex header (TeX mode) ! 6669: To indicate the bounds of the header in Plain @TeX{} mode, you insert two ! 6670: special strings in the file. Insert @samp{%**start of header} before the ! 6671: header, and @samp{%**end of header} after it. Each string must appear ! 6672: entirely on one line, but there may be other text on the line before or ! 6673: after. The lines containing the two strings are included in the header. ! 6674: If @samp{%**start of header} does not appear within the first 100 lines of ! 6675: the buffer, @kbd{C-c C-r} assumes that there is no header. ! 6676: ! 6677: In La@TeX{} mode, the header begins with @samp{\documentstyle} and ends ! 6678: with @samp{\begin@{document@}}. These are commands that La@TeX{} requires ! 6679: you to use in any case, so nothing special needs to be done to identify the ! 6680: header. ! 6681: ! 6682: @vindex TeX-mode-hook ! 6683: @vindex LaTeX-mode-hook ! 6684: @vindex plain-TeX-mode-hook ! 6685: Entering either kind of @TeX{} mode calls with no arguments the value of ! 6686: the variable @code{text-mode-hook}, if that value exists and is not ! 6687: @code{nil}; then it does the same with the variable @code{TeX-mode-hook}. ! 6688: Finally it does the same with either @code{plain-TeX-mode-hook} or ! 6689: @code{LaTeX-mode-hook}. ! 6690: ! 6691: @node Outline Mode,, TeX Mode, Text Mode ! 6692: @subsection Outline Mode ! 6693: @cindex outlines ! 6694: @cindex selective display ! 6695: @cindex invisible lines ! 6696: ! 6697: Outline mode is a major mode much like Text mode but intended for editing ! 6698: outlines. It allows you to make parts of the text temporarily invisible ! 6699: so that you can see just the overall structure of the outline. Type ! 6700: @kbd{M-x outline-mode} to turn on Outline mode in the current buffer. ! 6701: ! 6702: @vindex outline-mode-hook ! 6703: Entering Outline mode calls with no arguments the value of the variable ! 6704: @code{text-mode-hook}, if that value exists and is not @code{nil}; then it ! 6705: does the same with the variable @code{outline-mode-hook}. ! 6706: ! 6707: When a line is invisible in outline mode, it does not appear on the ! 6708: screen. The screen appears exactly as if the invisible line ! 6709: were deleted, except that an ellipsis (three periods in a row) appears ! 6710: at the end of the previous visible line (only one ellipsis no matter ! 6711: how many invisible lines follow). ! 6712: ! 6713: All editing commands treat the text of the invisible line as part of the ! 6714: previous visible line. For example, @kbd{C-n} moves onto the next visible ! 6715: line. Killing an entire visible line, including its terminating newline, ! 6716: really kills all the following invisible lines along with it; yanking it ! 6717: all back yanks the invisible lines and they remain invisible. ! 6718: ! 6719: @menu ! 6720: * Format: Outline Format. What the text of an outline looks like. ! 6721: * Motion: Outline Motion. Special commands for moving through outlines. ! 6722: * Visibility: Outline Visibility. Commands to control what is visible. ! 6723: @end menu ! 6724: ! 6725: @node Outline Format,Outline Motion,Outline Mode, Outline Mode ! 6726: @subsubsection Format of Outlines ! 6727: ! 6728: @cindex heading lines (Outline mode) ! 6729: @cindex body lines (Outline mode) ! 6730: Outline mode assumes that the lines in the buffer are of two types: ! 6731: @dfn{heading lines} and @dfn{body lines}. A heading line represents a topic in the ! 6732: outline. Heading lines start with one or more stars; the number of stars ! 6733: determines the depth of the heading in the outline structure. Thus, a ! 6734: heading line with one star is a major topic; all the heading lines with ! 6735: two stars between it and the next one-star heading are its subtopics; and ! 6736: so on. Any line that is not a heading line is a body line. Body lines ! 6737: belong to the preceding heading line. Here is an example: ! 6738: ! 6739: @example ! 6740: * Food ! 6741: ! 6742: This is the body, ! 6743: which says something about the topic of food. ! 6744: ! 6745: ** Delicious Food ! 6746: ! 6747: This is the body of the second-level header. ! 6748: ! 6749: ** Distasteful Food ! 6750: ! 6751: This could have ! 6752: a body too, with ! 6753: several lines. ! 6754: ! 6755: *** Dormitory Food ! 6756: ! 6757: * Shelter ! 6758: ! 6759: A second first-level topic with its header line. ! 6760: @end example ! 6761: ! 6762: A heading line together with all following body lines is called ! 6763: collectively an @dfn{entry}. A heading line together with all following ! 6764: deeper heading lines and their body lines is called a @dfn{subtree}. ! 6765: ! 6766: @vindex outline-regexp ! 6767: You can customize the criterion for distinguishing heading lines ! 6768: by setting the variable @code{outline-regexp}. Any line whose ! 6769: beginning has a match for this regexp is considered a heading line. ! 6770: Matches that start within a line (not at the beginning) do not count. ! 6771: The length of the matching text determines the level of the heading; ! 6772: longer matches make a more deeply nested level. Thus, for example, ! 6773: if a text formatter has commands @samp{@@chapter}, @samp{@@section} ! 6774: and @samp{@@subsection} to divide the document into chapters and ! 6775: sections, you could make those lines count as heading lines by ! 6776: setting @code{outline-regexp} to @samp{"@@chap\\|@@\\(sub\\)*section"}. ! 6777: Note the trick: the two words @samp{chapter} and @samp{section} are equally ! 6778: long, but by defining the regexp to match only @samp{chap} we ensure ! 6779: that the length of the text matched on a chapter heading is shorter, ! 6780: so that Outline mode will know that sections are contained in chapters. ! 6781: This works as long as no other command starts with @samp{@@chap}. ! 6782: ! 6783: Outline mode makes a line invisible by changing the newline before it ! 6784: into an ASCII Control-M (code 015). Most editing commands that work on ! 6785: lines treat an invisible line as part of the previous line because, ! 6786: strictly speaking, it @i{is} part of that line, since there is no longer a ! 6787: newline in between. When you save the file in Outline mode, Control-M ! 6788: characters are saved as newlines, so the invisible lines become ordinary ! 6789: lines in the file. But saving does not change the visibility status of a ! 6790: line inside Emacs. ! 6791: ! 6792: @node Outline Motion,Outline Visibility,Outline Format,Outline Mode ! 6793: @subsubsection Outline Motion Commands ! 6794: ! 6795: There are some special motion commands in Outline mode that move ! 6796: backward and forward to heading lines. ! 6797: ! 6798: @table @kbd ! 6799: @item C-c C-n ! 6800: Move point to the next visible heading line ! 6801: (@code{outline-next-visible-heading}). ! 6802: @item C-c C-p ! 6803: Move point to the previous visible heading line @* ! 6804: (@code{outline-previous-visible-heading}). ! 6805: @item C-c C-f ! 6806: Move point to the next visible heading line at the same level ! 6807: as the one point is on (@code{outline-forward-same-level}). ! 6808: @item C-c C-b ! 6809: Move point to the previous visible heading line at the same level ! 6810: (@code{outline-backward-same-level}). ! 6811: @item C-c C-u ! 6812: Move point up to a lower-level (more inclusive) visible heading line ! 6813: (@code{outline-up-heading}). ! 6814: @end table ! 6815: ! 6816: @findex outline-next-visible-heading ! 6817: @findex outline-previous-visible-heading ! 6818: @kindex C-c C-n (Outline mode) ! 6819: @kindex C-c C-p (Outline mode) ! 6820: @kbd{C-c C-n} (@code{next-visible-heading}) moves down to the next ! 6821: heading line. @kbd{C-c C-p} (@code{previous-visible-heading}) moves ! 6822: similarly backward. Both accept numeric arguments as repeat counts. The ! 6823: names emphasize that invisible headings are skipped, but this is not really ! 6824: a special feature. All editing commands that look for lines ignore the ! 6825: invisible lines automatically.@refill ! 6826: ! 6827: @findex outline-up-heading ! 6828: @findex outline-forward-same-level ! 6829: @findex outline-backward-same-level ! 6830: @kindex C-c C-f (Outline mode) ! 6831: @kindex C-c C-b (Outline mode) ! 6832: @kindex C-c C-u (Outline mode) ! 6833: More advanced motion commands understand the levels of headings. ! 6834: @kbd{C-c C-f} (@code{outline-forward-same-level}) and ! 6835: @kbd{C-c C-b} (@code{outline-backward-same-level}) move from one ! 6836: heading line to another visible heading at the same depth in ! 6837: the outline. @kbd{C-c C-u} (@code{outline-up-heading}) moves ! 6838: backward to another heading that is less deeply nested. ! 6839: ! 6840: @node Outline Visibility,,Outline Motion,Outline Mode ! 6841: @subsubsection Outline Visibility Commands ! 6842: ! 6843: The other special commands of outline mode are used to make lines visible ! 6844: or invisible. Their names all start with @code{hide} or @code{show}. ! 6845: Most of them fall into pairs of opposites. They are not undoable; instead, ! 6846: you can undo right past them. Making lines visible or invisible is simply ! 6847: not recorded by the undo mechanism. ! 6848: ! 6849: @table @kbd ! 6850: @item M-x hide-body ! 6851: Make all body lines in the buffer invisible. ! 6852: @item M-x show-all ! 6853: Make all lines in the buffer visible. ! 6854: @item C-c C-h ! 6855: Make everything under this heading invisible, not including this ! 6856: heading itself@* (@code{hide-subtree}). ! 6857: @item C-c C-s ! 6858: Make everything under this heading visible, including body, ! 6859: subheadings, and their bodies (@code{show-subtree}). ! 6860: @item M-x hide-leaves ! 6861: Make the body of this heading line, and of all its subheadings, ! 6862: invisible. ! 6863: @item M-x show-branches ! 6864: Make all subheadings of this heading line, at all levels, visible. ! 6865: @item C-c C-i ! 6866: Make immediate subheadings (one level down) of this heading line ! 6867: visible (@code{show-children}). ! 6868: @item M-x hide-entry ! 6869: Make this heading line's body invisible. ! 6870: @item M-x show-entry ! 6871: Make this heading line's body visible. ! 6872: @end table ! 6873: ! 6874: @findex hide-entry ! 6875: @findex show-entry ! 6876: Two commands that are exact opposites are @kbd{M-x hide-entry} and ! 6877: @kbd{M-x show-entry}. They are used with point on a heading line, and ! 6878: apply only to the body lines of that heading. The subtopics and their ! 6879: bodies are not affected. ! 6880: ! 6881: @findex hide-subtree ! 6882: @findex show-subtree ! 6883: @kindex C-c C-s (Outline mode) ! 6884: @kindex C-c C-h (Outline mode) ! 6885: @cindex subtree (Outline mode) ! 6886: Two more powerful opposites are @kbd{C-c C-h} (@code{hide-subtree}) and ! 6887: @kbd{C-c C-s} (@code{show-subtree}). Both expect to be used when point is ! 6888: on a heading line, and both apply to all the lines of that heading's ! 6889: @dfn{subtree}: its body, all its subheadings, both direct and indirect, and ! 6890: all of their bodies. In other words, the subtree contains everything ! 6891: following this heading line, up to and not including the next heading of ! 6892: the same or higher rank.@refill ! 6893: ! 6894: @findex hide-leaves ! 6895: @findex show-branches ! 6896: Intermediate between a visible subtree and an invisible one is having ! 6897: all the subheadings visible but none of the body. There are two commands ! 6898: for doing this, depending on whether you want to hide the bodies or ! 6899: make the subheadings visible. They are @kbd{M-x hide-leaves} and ! 6900: @kbd{M-x show-branches}. ! 6901: ! 6902: @kindex C-c C-i (Outline mode) ! 6903: @findex show-children ! 6904: A little weaker than @code{show-branches} is @kbd{C-c C-i} ! 6905: (@code{show-children}). It makes just the direct subheadings ! 6906: visible---those one level down. Deeper subheadings remain invisible, if ! 6907: they were invisible.@refill ! 6908: ! 6909: @findex hide-body ! 6910: @findex show-all ! 6911: Two commands have a blanket effect on the whole file. @kbd{M-x hide-body} ! 6912: makes all body lines invisible, so that you see just the outline structure. ! 6913: @kbd{M-x show-all} makes all lines visible. These commands can be thought ! 6914: of as a pair of opposites even though @kbd{M-x show-all} applies to more ! 6915: than just body lines. ! 6916: ! 6917: @vindex selective-display-ellipses ! 6918: The use of ellipses at the ends of visible lines can be turned off ! 6919: by setting @code{selective-display-ellipses} to @code{nil}. Then there ! 6920: is no visible indication of the presence of invisible lines. ! 6921: ! 6922: @node Words, Sentences, Text Mode, Text ! 6923: @section Words ! 6924: @cindex words ! 6925: @cindex Meta ! 6926: ! 6927: Emacs has commands for moving over or operating on words. By convention, ! 6928: the keys for them are all @kbd{Meta-} characters. ! 6929: ! 6930: @c widecommands ! 6931: @table @kbd ! 6932: @item M-f ! 6933: Move forward over a word (@code{forward-word}). ! 6934: @item M-b ! 6935: Move backward over a word (@code{backward-word}). ! 6936: @item M-d ! 6937: Kill up to the end of a word (@code{kill-word}). ! 6938: @item M-@key{DEL} ! 6939: Kill back to the beginning of a word (@code{backward-kill-word}). ! 6940: @item M-@@ ! 6941: Mark the end of the next word (@code{mark-word}). ! 6942: @item M-t ! 6943: Transpose two words; drag a word forward ! 6944: or backward across other words (@code{transpose-words}). ! 6945: @end table ! 6946: ! 6947: Notice how these keys form a series that parallels the ! 6948: character-based @kbd{C-f}, @kbd{C-b}, @kbd{C-d}, @kbd{C-t} and ! 6949: @key{DEL}. @kbd{M-@@} is related to @kbd{C-@@}, which is an alias for ! 6950: @kbd{C-@key{SPC}}.@refill ! 6951: ! 6952: @kindex M-f ! 6953: @kindex M-b ! 6954: @findex forward-word ! 6955: @findex backward-word ! 6956: The commands @kbd{Meta-f} (@code{forward-word}) and @kbd{Meta-b} ! 6957: (@code{backward-word}) move forward and backward over words. They are thus ! 6958: analogous to @kbd{Control-f} and @kbd{Control-b}, which move over single ! 6959: characters. Like their @kbd{Control-} analogues, @kbd{Meta-f} and ! 6960: @kbd{Meta-b} move several words if given an argument. @kbd{Meta-f} with a ! 6961: negative argument moves backward, and @kbd{Meta-b} with a negative argument ! 6962: moves forward. Forward motion stops right after the last letter of the ! 6963: word, while backward motion stops right before the first letter.@refill ! 6964: ! 6965: @kindex M-d ! 6966: @findex kill-word ! 6967: @kbd{Meta-d} (@code{kill-word}) kills the word after point. To be ! 6968: precise, it kills everything from point to the place @kbd{Meta-f} would ! 6969: move to. Thus, if point is in the middle of a word, @kbd{Meta-d} kills ! 6970: just the part after point. If some punctuation comes between point and the ! 6971: next word, it is killed along with the word. (If you wish to kill only the ! 6972: next word but not the punctuation before it, simply do @kbd{Meta-f} to get ! 6973: the end, and kill the word backwards with @kbd{Meta-@key{DEL}}.) ! 6974: @kbd{Meta-d} takes arguments just like @kbd{Meta-f}. ! 6975: ! 6976: @findex backward-kill-word ! 6977: @kindex M-DEL ! 6978: @kbd{Meta-@key{DEL}} (@code{backward-kill-word}) kills the word before ! 6979: point. It kills everything from point back to where @kbd{Meta-b} would ! 6980: move to. If point is after the space in @w{@samp{FOO, BAR}}, then ! 6981: @w{@samp{FOO, }} is killed. (If you wish to kill just @samp{FOO}, do ! 6982: @kbd{Meta-b Meta-d} instead of @kbd{Meta-@key{DEL}}.) ! 6983: ! 6984: @cindex transposition ! 6985: @kindex M-t ! 6986: @findex transpose-words ! 6987: @kbd{Meta-t} (@code{transpose-words}) exchanges the word before or ! 6988: containing point with the following word. The delimiter characters between ! 6989: the words do not move. For example, @w{@samp{FOO, BAR}} transposes into ! 6990: @w{@samp{BAR, FOO}} rather than @samp{@w{BAR FOO,}}. @xref{Transpose}, for ! 6991: more on transposition and on arguments to transposition commands. ! 6992: ! 6993: @kindex M-@@ ! 6994: @findex mark-word ! 6995: To operate on the next @var{n} words with an operation which applies ! 6996: between point and mark, you can either set the mark at point and then move ! 6997: over the words, or you can use the command @kbd{Meta-@@} (@code{mark-word}) ! 6998: which does not move point, but sets the mark where @kbd{Meta-f} would move ! 6999: to. It can be given arguments just like @kbd{Meta-f}. ! 7000: ! 7001: @cindex syntax table ! 7002: The word commands' understanding of syntax is completely controlled by ! 7003: the syntax table. Any character can, for example, be declared to be a word ! 7004: delimiter. @xref{Syntax}. ! 7005: ! 7006: @node Sentences, Paragraphs, Words, Text ! 7007: @section Sentences ! 7008: @cindex sentences ! 7009: ! 7010: The Emacs commands for manipulating sentences and paragraphs are mostly ! 7011: on @kbd{Meta-} keys, so as to be like the word-handling commands. ! 7012: ! 7013: @table @kbd ! 7014: @item M-a ! 7015: Move back to the beginning of the sentence (@code{backward-sentence}). ! 7016: @item M-e ! 7017: Move forward to the end of the sentence (@code{forward-sentence}). ! 7018: @item M-k ! 7019: Kill forward to the end of the sentence (@code{kill-sentence}). ! 7020: @item C-x @key{DEL} ! 7021: Kill back to the beginning of the sentence @*(@code{backward-kill-sentence}). ! 7022: @end table ! 7023: ! 7024: @kindex M-a ! 7025: @kindex M-e ! 7026: @findex backward-sentence ! 7027: @findex forward-sentence ! 7028: The commands @kbd{Meta-a} and @kbd{Meta-e} (@code{backward-sentence} and ! 7029: @code{forward-sentence}) move to the beginning and end of the current ! 7030: sentence, respectively. They were chosen to resemble @kbd{Control-a} and ! 7031: @kbd{Control-e}, which move to the beginning and end of a line. Unlike ! 7032: them, @kbd{Meta-a} and @kbd{Meta-e} if repeated or given numeric arguments ! 7033: move over successive sentences. Emacs assumes that the typist's convention ! 7034: is followed, and thus considers a sentence to end wherever there is a ! 7035: @samp{.}, @samp{?} or @samp{!} followed by the end of a line or two spaces, ! 7036: with any number of @samp{)}, @samp{]}, @samp{'}, or @samp{"} characters ! 7037: allowed in between. A sentence also begins or ends wherever a paragraph ! 7038: begins or ends.@refill ! 7039: ! 7040: Neither @kbd{M-a} nor @kbd{M-e} moves past the newline or spaces beyond ! 7041: the sentence edge at which it is stopping. ! 7042: ! 7043: @kindex M-k ! 7044: @kindex C-x DEL ! 7045: @findex kill-sentence ! 7046: @findex backward-kill-sentence ! 7047: Just as @kbd{C-a} and @kbd{C-e} have a kill command, @kbd{C-k}, to go ! 7048: with them, so @kbd{M-a} and @kbd{M-e} have a corresponding kill command ! 7049: @kbd{M-k} (@code{kill-sentence}) which kills from point to the end of the ! 7050: sentence. With minus one as an argument it kills back to the beginning of ! 7051: the sentence. Larger arguments serve as a repeat count.@refill ! 7052: ! 7053: There is a special command, @kbd{C-x @key{DEL}} ! 7054: (@code{backward-kill-sentence}) for killing back to the beginning of a ! 7055: sentence, because this is useful when you change your mind in the middle of ! 7056: composing text.@refill ! 7057: ! 7058: @vindex sentence-end ! 7059: The variable @code{sentence-end} controls recognition of the end of a ! 7060: sentence. It is a regexp that matches the last few characters of a ! 7061: sentence, together with the whitespace following the sentence. Its ! 7062: normal value is ! 7063: ! 7064: @example ! 7065: "[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*" ! 7066: @end example ! 7067: ! 7068: @noindent ! 7069: This example is explained in the section on regexps. @xref{Regexps}. ! 7070: ! 7071: @node Paragraphs, Pages, Sentences, Text ! 7072: @section Paragraphs ! 7073: @cindex paragraphs ! 7074: @kindex M-[ ! 7075: @kindex M-] ! 7076: @findex backward-paragraph ! 7077: @findex forward-paragraph ! 7078: ! 7079: The Emacs commands for manipulating paragraphs are also @kbd{Meta-} ! 7080: keys. ! 7081: ! 7082: @table @kbd ! 7083: @item M-[ ! 7084: Move back to previous paragraph beginning @*(@code{backward-paragraph}). ! 7085: @item M-] ! 7086: Move forward to next paragraph end (@code{forward-paragraph}). ! 7087: @item M-h ! 7088: Put point and mark around this or next paragraph (@code{mark-paragraph}). ! 7089: @end table ! 7090: ! 7091: @kbd{Meta-[} moves to the beginning of the current or previous paragraph, ! 7092: while @kbd{Meta-]} moves to the end of the current or next paragraph. ! 7093: Blank lines and text formatter command lines separate paragraphs and are ! 7094: not part of any paragraph. Also, an indented line starts a new ! 7095: paragraph. ! 7096: ! 7097: In major modes for programs (as opposed to Text mode), paragraphs begin ! 7098: and end only at blank lines. This makes the paragraph commands continue to ! 7099: be useful even though there are no paragraphs per se. ! 7100: ! 7101: When there is a fill prefix, then paragraphs are delimited by all lines ! 7102: which don't start with the fill prefix. @xref{Filling}. ! 7103: ! 7104: @kindex M-h ! 7105: @findex mark-paragraph ! 7106: When you wish to operate on a paragraph, you can use the command ! 7107: @kbd{Meta-h} (@code{mark-paragraph}) to set the region around it. This ! 7108: command puts point at the beginning and mark at the end of the paragraph ! 7109: point was in. If point is between paragraphs (in a run of blank lines, or ! 7110: at a boundary), the paragraph following point is surrounded by point and ! 7111: mark. If there are blank lines preceding the first line of the paragraph, ! 7112: one of these blank lines is included in the region. Thus, for example, ! 7113: @kbd{M-h C-w} kills the paragraph around or after point. ! 7114: ! 7115: @vindex paragraph-start ! 7116: @vindex paragraph-separate ! 7117: The precise definition of a paragraph boundary is controlled by the ! 7118: variables @code{paragraph-separate} and @code{paragraph-start}. The value ! 7119: of @code{paragraph-start} is a regexp that should match any line that ! 7120: either starts or separates paragraphs. The value of ! 7121: @code{paragraph-separate} is another regexp that should match only lines ! 7122: that separate paragraphs without being part of any paragraph. Lines that ! 7123: start a new paragraph and are contained in it must match both regexps. For ! 7124: example, normally @code{paragraph-start} is @code{"^[ @t{\}t@t{\}n@t{\}f]"} ! 7125: and @code{paragraph-separate} is @code{"^[ @t{\}t@t{\}f]*$"}.@refill ! 7126: ! 7127: Normally it is desirable for page boundaries to separate paragraphs. ! 7128: The default values of these variables recognize the usual separator for ! 7129: pages. ! 7130: ! 7131: @node Pages, Filling, Paragraphs, Text ! 7132: @section Pages ! 7133: ! 7134: @cindex pages ! 7135: @cindex formfeed ! 7136: Files are often thought of as divided into @dfn{pages} by the ! 7137: @dfn{formfeed} character (ASCII Control-L, octal code 014). For example, ! 7138: if a file is printed on a line printer, each page of the file, in this ! 7139: sense, will start on a new page of paper. Emacs treats a page-separator ! 7140: character just like any other character. It can be inserted with @kbd{C-q ! 7141: C-l}, or deleted with @key{DEL}. Thus, you are free to paginate your file ! 7142: or not. However, since pages are often meaningful divisions of the file, ! 7143: commands are provided to move over them and operate on them. ! 7144: ! 7145: @c WideCommands ! 7146: @table @kbd ! 7147: @item C-x [ ! 7148: Move point to previous page boundary (@code{backward-page}). ! 7149: @item C-x ] ! 7150: Move point to next page boundary (@code{forward-page}). ! 7151: @item C-x C-p ! 7152: Put point and mark around this page (or another page) (@code{mark-page}). ! 7153: @item C-x l ! 7154: Count the lines in this page (@code{count-lines-page}). ! 7155: @end table ! 7156: ! 7157: @kindex C-x [ ! 7158: @kindex C-x ] ! 7159: @findex forward-page ! 7160: @findex backward-page ! 7161: The @kbd{C-x [} (@code{backward-page}) command moves point to immediately ! 7162: after the previous page delimiter. If point is already right after a page ! 7163: delimiter, it skips that one and stops at the previous one. A numeric ! 7164: argument serves as a repeat count. The @kbd{C-x ]} (@code{forward-page}) ! 7165: command moves forward past the next page delimiter. ! 7166: ! 7167: @kindex C-x C-p ! 7168: @findex mark-page ! 7169: The @kbd{C-x C-p} command (@code{mark-page}) puts point at the beginning ! 7170: of the current page and the mark at the end. The page delimiter at the end ! 7171: is included (the mark follows it). The page delimiter at the front is ! 7172: excluded (point follows it). This command can be followed by @kbd{C-w} to ! 7173: kill a page which is to be moved elsewhere. If it is inserted after a page ! 7174: delimiter, at a place where @kbd{C-x ]} or @kbd{C-x [} would take you, then ! 7175: the page will be properly delimited before and after once again. ! 7176: ! 7177: A numeric argument to @kbd{C-x C-p} is used to specify which page to go ! 7178: to, relative to the current one. Zero means the current page. One means ! 7179: the next page, and @minus{}1 means the previous one. ! 7180: ! 7181: @kindex C-x l ! 7182: @findex count-lines-page ! 7183: The @kbd{C-x l} command (@code{count-lines-page}) is good for deciding ! 7184: where to break a page in two. It prints in the echo area the total number ! 7185: of lines in the current page, and then divides it up into those preceding ! 7186: the current line and those following, as in ! 7187: ! 7188: @example ! 7189: Page has 96 (72+25) lines ! 7190: @end example ! 7191: ! 7192: @noindent ! 7193: Notice that the sum is off by one; this is correct if point is not at the ! 7194: beginning of a line. ! 7195: ! 7196: @vindex page-delimiter ! 7197: The variable @code{page-delimiter} should have as its value a regexp that ! 7198: matches the beginning of a line that separates pages. This is what defines ! 7199: where pages begin. The normal value of this variable is @code{"^@t{\}f"}, ! 7200: which matches a formfeed character at the beginning of a line. ! 7201: ! 7202: @node Filling, Case, Pages, Text ! 7203: @section Filling Text ! 7204: @cindex filling ! 7205: ! 7206: With Auto Fill mode, text can be @dfn{filled} (broken up into lines that ! 7207: fit in a specified width) as you insert it. If you alter existing text it ! 7208: may no longer be properly filled; then explicit commands for filling can be ! 7209: used. ! 7210: ! 7211: @menu ! 7212: * Auto Fill:: Auto Fill mode breaks long lines automatically. ! 7213: * Fill Commands:: Commands to refill paragraphs and center lines. ! 7214: * Fill Prefix:: Filling when every line is indented or in a comment, etc. ! 7215: @end menu ! 7216: ! 7217: @node Auto Fill, Fill Commands, Filling, Filling ! 7218: @subsection Auto Fill Mode ! 7219: ! 7220: @cindex Auto Fill mode ! 7221: ! 7222: @dfn{Auto Fill} mode is a minor mode in which lines are broken ! 7223: automatically when they become too wide. Breaking happens only when ! 7224: you type a @key{SPC} or @key{RET}. ! 7225: ! 7226: @table @kbd ! 7227: @item M-x auto-fill-mode ! 7228: Enable or disable Auto Fill mode. ! 7229: @item @key{SPC} ! 7230: @itemx @key{RET} ! 7231: In Auto Fill mode, break lines when appropriate. ! 7232: @end table ! 7233: ! 7234: @findex auto-fill-mode ! 7235: @kbd{M-x auto-fill-mode} turns Auto Fill mode on if it was off, or off if ! 7236: it was on. With a positive numeric argument it always turns Auto Fill mode ! 7237: on, and with a negative argument always turns it off. You can see when ! 7238: Auto Fill mode is in effect by the presence of the word @samp{Fill} in the ! 7239: mode line, inside the parentheses. Auto Fill mode is a minor mode, turned ! 7240: on or off for each buffer individually. @xref{Minor Modes}. ! 7241: ! 7242: In Auto Fill mode, lines are broken automatically at spaces when they get ! 7243: longer than the desired width. Line breaking and rearrangement takes place ! 7244: only when you type @key{SPC} or @key{RET}. If you wish to insert a space ! 7245: or newline without permitting line-breaking, type @kbd{C-q @key{SPC}} or ! 7246: @kbd{C-q @key{LFD}} (recall that a newline is really a linefeed). Also, ! 7247: @kbd{C-o} inserts a newline without line breaking. ! 7248: ! 7249: Auto Fill mode works well with Lisp mode, because when it makes a new ! 7250: line in Lisp mode it indents that line with @key{TAB}. If a line ending in ! 7251: a comment gets too long, the text of the comment is split into two ! 7252: comment lines. Optionally new comment delimiters are inserted at the end of ! 7253: the first line and the beginning of the second so that each line is ! 7254: a separate comment; the variable @code{comment-multi-line} controls the ! 7255: choice (@pxref{Comments}). ! 7256: ! 7257: Auto Fill mode does not refill entire paragraphs. It can break lines but ! 7258: cannot merge lines. So editing in the middle of a paragraph can result in ! 7259: a paragraph that is not correctly filled. The easiest way to make the ! 7260: paragraph properly filled again is usually with the explicit fill commands. ! 7261: ! 7262: Many users like Auto Fill mode and want to use it in all text files. ! 7263: The section on init files says how to arrange this permanently for yourself. ! 7264: @xref{Init File}. ! 7265: ! 7266: @node Fill Commands, Fill Prefix, Auto Fill, Filling ! 7267: @subsection Explicit Fill Commands ! 7268: ! 7269: @table @kbd ! 7270: @item M-q ! 7271: Fill current paragraph (@code{fill-paragraph}). ! 7272: @item M-g ! 7273: Fill each paragraph in the region (@code{fill-region}). ! 7274: @item C-x f ! 7275: Set the fill column (@code{set-fill-column}). ! 7276: @item M-x fill-region-as-paragraph. ! 7277: Fill the region, considering it as one paragraph. ! 7278: @item M-s ! 7279: Center a line. ! 7280: @end table ! 7281: ! 7282: @kindex M-q ! 7283: @findex fill-paragraph ! 7284: To refill a paragraph, use the command @kbd{Meta-q} ! 7285: (@code{fill-paragraph}). It causes the paragraph that point is inside, or ! 7286: the one after point if point is between paragraphs, to be refilled. All ! 7287: the line-breaks are removed, and then new ones are inserted where ! 7288: necessary. @kbd{M-q} can be undone with @kbd{C-_}. @xref{Undo}.@refill ! 7289: ! 7290: @kindex M-g ! 7291: @findex fill-region ! 7292: To refill many paragraphs, use @kbd{M-g} (@code{fill-region}), which ! 7293: divides the region into paragraphs and fills each of them. ! 7294: ! 7295: @findex fill-region-as-paragraph ! 7296: @kbd{Meta-q} and @kbd{Meta-g} use the same criteria as @kbd{Meta-h} for ! 7297: finding paragraph boundaries (@pxref{Paragraphs}). For more control, you ! 7298: can use @kbd{M-x fill-region-as-paragraph}, which refills everything ! 7299: between point and mark. This command recognizes only blank lines as ! 7300: paragraph separators.@refill ! 7301: ! 7302: @cindex justification ! 7303: A numeric argument to @kbd{M-g} or @kbd{M-q} causes it to @dfn{justify} ! 7304: the text as well as filling it. This means that extra spaces are inserted ! 7305: to make the right margin line up exactly at the fill column. To remove the ! 7306: extra spaces, use @kbd{M-q} or @kbd{M-g} with no argument.@refill ! 7307: ! 7308: @kindex M-s ! 7309: @cindex centering ! 7310: @findex center-line ! 7311: The command @kbd{Meta-s} (@code{center-line}) centers the current line ! 7312: within the current fill column. With an argument, it centers several lines ! 7313: individually and moves past them. ! 7314: ! 7315: @vindex fill-column ! 7316: The maximum line width for filling is in the variable @code{fill-column}. ! 7317: Altering the value of @code{fill-column} makes it local to the current ! 7318: buffer; until that time, the default value is in effect. The default is ! 7319: initially 70. @xref{Locals}. ! 7320: ! 7321: @kindex C-x f ! 7322: @findex set-fill-column ! 7323: The easiest way to set @code{fill-column} is to use the command @kbd{C-x ! 7324: f} (@code{set-fill-column}). With no argument, it sets @code{fill-column} ! 7325: to the current horizontal position of point. With a numeric argument, it ! 7326: uses that as the new fill column. ! 7327: ! 7328: @node Fill Prefix,, Fill Commands, Filling ! 7329: @subsection The Fill Prefix ! 7330: ! 7331: @cindex fill prefix ! 7332: To fill a paragraph in which each line starts with a special marker ! 7333: (which might be a few spaces, giving an indented paragraph), use the ! 7334: @dfn{fill prefix} feature. The fill prefix is a string which Emacs expects ! 7335: every line to start with, and which is not included in filling. ! 7336: ! 7337: @table @kbd ! 7338: @item C-x . ! 7339: Set the fill prefix (@code{set-fill-prefix}). ! 7340: @item M-q ! 7341: Fill a paragraph using current fill prefix (@code{fill-paragraph}). ! 7342: @item M-x fill-individual-paragraphs ! 7343: Fill the region, considering each change of indentation as starting a ! 7344: new paragraph. ! 7345: @end table ! 7346: ! 7347: @kindex C-x . ! 7348: @findex set-fill-prefix ! 7349: To specify a fill prefix, move to a line that starts with the desired ! 7350: prefix, put point at the end of the prefix, and give the command ! 7351: @w{@kbd{C-x .}}@: (@code{set-fill-prefix}). That's a period after the ! 7352: @kbd{C-x}. To turn off the fill prefix, specify an empty prefix: type ! 7353: @w{@kbd{C-x .}}@: with point at the beginning of a line.@refill ! 7354: ! 7355: When a fill prefix is in effect, the fill commands remove the fill prefix ! 7356: from each line before filling and insert it on each line after filling. ! 7357: The fill prefix is also inserted on new lines made automatically by Auto ! 7358: Fill mode. Lines that do not start with the fill prefix are considered to ! 7359: start paragraphs, both in @kbd{M-q} and the paragraph commands; this is ! 7360: just right if you are using paragraphs with hanging indentation (every line ! 7361: indented except the first one). Lines which are blank or indented once the ! 7362: prefix is removed also separate or start paragraphs; this is what you want ! 7363: if you are writing multi-paragraph comments with a comment delimiter on ! 7364: each line. ! 7365: ! 7366: @vindex fill-prefix ! 7367: The fill prefix is stored in the variable @code{fill-prefix}. Its value ! 7368: is a string, or @code{nil} when there is no fill prefix. This is a ! 7369: per-buffer variable; altering the variable affects only the current buffer, ! 7370: but there is a default value which you can change as well. @xref{Locals}. ! 7371: ! 7372: @findex fill-individual-paragraphs ! 7373: Another way to use fill prefixes is through @kbd{M-x ! 7374: fill-individual-paragraphs}. This function divides the region into groups ! 7375: of consecutive lines with the same amount and kind of indentation and fills ! 7376: each group as a paragraph using its indentation as a fill prefix. ! 7377: ! 7378: @node Case,, Filling, Text ! 7379: @section Case Conversion Commands ! 7380: @cindex case conversion ! 7381: ! 7382: Emacs has commands for converting either a single word or any arbitrary ! 7383: range of text to upper case or to lower case. ! 7384: ! 7385: @c WideCommands ! 7386: @table @kbd ! 7387: @item M-l ! 7388: Convert following word to lower case (@code{downcase-word}). ! 7389: @item M-u ! 7390: Convert following word to upper case (@code{upcase-word}). ! 7391: @item M-c ! 7392: Capitalize the following word (@code{capitalize-word}). ! 7393: @item C-x C-l ! 7394: Convert region to lower case (@code{downcase-region}). ! 7395: @item C-x C-u ! 7396: Convert region to upper case (@code{upcase-region}). ! 7397: @end table ! 7398: ! 7399: @kindex M-l ! 7400: @kindex M-u ! 7401: @kindex M-c ! 7402: @cindex words ! 7403: @findex downcase-word ! 7404: @findex upcase-word ! 7405: @findex capitalize-word ! 7406: The word conversion commands are the most useful. @kbd{Meta-l} ! 7407: (@code{downcase-word}) converts the word after point to lower case, moving ! 7408: past it. Thus, repeating @kbd{Meta-l} converts successive words. ! 7409: @kbd{Meta-u} (@code{upcase-word}) converts to all capitals instead, while ! 7410: @kbd{Meta-c} (@code{capitalize-word}) puts the first letter of the word ! 7411: into upper case and the rest into lower case. All these commands convert ! 7412: several words at once if given an argument. They are especially convenient ! 7413: for converting a large amount of text from all upper case to mixed case, ! 7414: because you can move through the text using @kbd{M-l}, @kbd{M-u} or ! 7415: @kbd{M-c} on each word as appropriate, occasionally using @kbd{M-f} instead ! 7416: to skip a word. ! 7417: ! 7418: When given a negative argument, the word case conversion commands apply ! 7419: to the appropriate number of words before point, but do not move point. ! 7420: This is convenient when you have just typed a word in the wrong case: you ! 7421: can give the case conversion command and continue typing. ! 7422: ! 7423: If a word case conversion command is given in the middle of a word, it ! 7424: applies only to the part of the word which follows point. This is just ! 7425: like what @kbd{Meta-d} (@code{kill-word}) does. With a negative argument, ! 7426: case conversion applies only to the part of the word before point. ! 7427: ! 7428: @kindex C-x C-l ! 7429: @kindex C-x C-u ! 7430: @cindex region ! 7431: @findex downcase-region ! 7432: @findex upcase-region ! 7433: The other case conversion commands are @kbd{C-x C-u} ! 7434: (@code{upcase-region}) and @kbd{C-x C-l} (@code{downcase-region}), which ! 7435: convert everything between point and mark to the specified case. Point and ! 7436: mark do not move.@refill ! 7437: ! 7438: @node Programs, Running, Text, Top ! 7439: @chapter Editing Programs ! 7440: @cindex Lisp ! 7441: @cindex C ! 7442: ! 7443: Emacs has many commands designed to understand the syntax of programming ! 7444: languages such as Lisp and C. These commands can ! 7445: ! 7446: @itemize @bullet ! 7447: @item ! 7448: Move over or kill balanced expressions or @dfn{sexps} (@pxref{Lists}). ! 7449: @item ! 7450: Move over or mark top-level balanced expressions (@dfn{defuns}, in Lisp; ! 7451: functions, in C). ! 7452: @item ! 7453: Show how parentheses balance (@pxref{Matching}). ! 7454: @item ! 7455: Insert, kill or align comments (@pxref{Comments}). ! 7456: @item ! 7457: Follow the usual indentation conventions of the language ! 7458: (@pxref{Grinding}). ! 7459: @end itemize ! 7460: ! 7461: The commands for words, sentences and paragraphs are very useful in ! 7462: editing code even though their canonical application is for editing human ! 7463: language text. Most symbols contain words (@pxref{Words}); sentences can ! 7464: be found in strings and comments (@pxref{Sentences}). Paragraphs per se ! 7465: are not present in code, but the paragraph commands are useful anyway, ! 7466: because Lisp mode and C mode define paragraphs to begin and end at blank ! 7467: lines (@pxref{Paragraphs}). Judicious use of blank lines to make the ! 7468: program clearer will also provide interesting chunks of text for the ! 7469: paragraph commands to work on. ! 7470: ! 7471: The selective display feature is useful for looking at the overall ! 7472: structure of a function (@pxref{Selective Display}). This feature causes ! 7473: only the lines that are indented less than a specified amount to appear ! 7474: on the screen. ! 7475: ! 7476: @menu ! 7477: * Program Modes:: Major modes for editing programs. ! 7478: * Lists:: Expressions with balanced parentheses. ! 7479: There are editing commands to operate on them. ! 7480: * Defuns:: Each program is made up of separate functions. ! 7481: There are editing commands to operate on them. ! 7482: * Grinding:: Adjusting indentation to show the nesting. ! 7483: * Matching:: Insertion of a close-delimiter flashes matching open. ! 7484: * Comments:: Inserting, illing and aligning comments. ! 7485: * Balanced Editing:: Inserting two matching parentheses at once, etc. ! 7486: * Lisp Completion:: Completion on symbol names in Lisp code. ! 7487: * Documentation:: Getting documentation of functions you plan to call. ! 7488: * Change Log:: Maintaining a change history for your program. ! 7489: * Tags:: Go direct to any function in your program in one ! 7490: command. Tags remembers which file it is in. ! 7491: * Fortran:: Fortran mode and its special features. ! 7492: @end menu ! 7493: ! 7494: @node Program Modes, Lists, Programs, Programs ! 7495: @section Major Modes for Programming Languages ! 7496: ! 7497: @cindex Lisp mode ! 7498: @cindex C mode ! 7499: @cindex Scheme mode ! 7500: Emacs also has major modes for the programming languages Lisp, Scheme (a ! 7501: variant of Lisp), C, Fortran and Muddle. Ideally, a major mode should be ! 7502: implemented for each programming language that you might want to edit with ! 7503: Emacs; but often the mode for one language can serve for other ! 7504: syntactically similar languages. The language modes that exist are those ! 7505: that someone decided to take the trouble to write. ! 7506: ! 7507: There are several forms of Lisp mode, which differ in the way they ! 7508: interface to Lisp execution. @xref{Lisp Modes}. ! 7509: ! 7510: Each of the programming language modes defines the @key{TAB} key to run ! 7511: an indentation function that knows the indentation conventions of that ! 7512: language and updates the current line's indentation accordingly. For ! 7513: example, in C mode @key{TAB} is bound to @code{c-indent-line}. @key{LFD} ! 7514: is normally defined to do @key{RET} followed by @key{TAB}; thus, it too ! 7515: indents in a mode-specific fashion. ! 7516: ! 7517: @kindex DEL ! 7518: @findex backward-delete-char-untabify ! 7519: In most programming languages, indentation is likely to vary from line to ! 7520: line. So the major modes for those languages rebind @key{DEL} to treat a ! 7521: tab as if it were the equivalent number of spaces (using the command ! 7522: @code{backward-delete-char-untabify}). This makes it possible to rub out ! 7523: indentation one column at a time without worrying whether it is made up of ! 7524: spaces or tabs. Use @kbd{C-b C-d} to delete a tab character before point, ! 7525: in these modes. ! 7526: ! 7527: Programming language modes define paragraphs to be separated only by ! 7528: blank lines, so that the paragraph commands remain useful. Auto Fill mode, ! 7529: if enabled in a programming language major mode, indents the new lines ! 7530: which it creates. ! 7531: ! 7532: @cindex mode hook ! 7533: @vindex c-mode-hook ! 7534: @vindex lisp-mode-hook ! 7535: @vindex emacs-lisp-mode-hook ! 7536: @vindex lisp-interaction-mode-hook ! 7537: @vindex scheme-mode-hook ! 7538: @vindex muddle-mode-hook ! 7539: Turning on a major mode calls a user-supplied function called the ! 7540: @dfn{mode hook}, which is the value of a Lisp variable. For example, ! 7541: turning on C mode calls the value of the variable @code{c-mode-hook} if ! 7542: that value exists and is non-@code{nil}. Mode hook variables for other ! 7543: programming language modes include @code{lisp-mode-hook}, ! 7544: @code{emacs-lisp-mode-hook}, @code{lisp-interaction-mode-hook}, ! 7545: @code{scheme-mode-hook} and @code{muddle-mode-hook}. The mode hook ! 7546: function receives no arguments.@refill ! 7547: ! 7548: @node Lists, Defuns, Program Modes, Programs ! 7549: @section Lists and Sexps ! 7550: ! 7551: @cindex Control-Meta ! 7552: By convention, Emacs keys for dealing with balanced expressions are ! 7553: usually @kbd{Control-Meta-} characters. They tend to be analogous in ! 7554: function to their @kbd{Control-} and @kbd{Meta-} equivalents. These commands ! 7555: are usually thought of as pertaining to expressions in programming ! 7556: languages, but can be useful with any language in which some sort of ! 7557: parentheses exist (including English). ! 7558: ! 7559: @cindex list ! 7560: @cindex sexp ! 7561: @cindex expression ! 7562: These commands fall into two classes. Some deal only with @dfn{lists} ! 7563: (parenthetical groupings). They see nothing except parentheses, brackets, ! 7564: braces (whichever ones must balance in the language you are working with), ! 7565: and escape characters that might be used to quote those. ! 7566: ! 7567: The other commands deal with expressions or @dfn{sexps}. The word `sexp' ! 7568: is derived from @dfn{s-expression}, the ancient term for an expression in ! 7569: Lisp. But in Emacs, the notion of `sexp' is not limited to Lisp. It ! 7570: refers to an expression in whatever language your program is written in. ! 7571: Each programming language has its own major mode, which customizes the ! 7572: syntax tables so that expressions in that language count as sexps. ! 7573: ! 7574: Sexps typically include symbols, numbers, and string constants, as well ! 7575: as anything contained in parentheses, brackets or braces. ! 7576: ! 7577: In languages that use prefix and infix operators, such as C, it is not ! 7578: possible for all expressions to be sexps. For example, C mode does not ! 7579: recognize @samp{foo + bar} as a sexp, even though it @i{is} a C expression; ! 7580: it recognizes @samp{foo} as one sexp and @samp{bar} as another, with the ! 7581: @samp{+} as punctuation between them. This is a fundamental ambiguity: ! 7582: both @samp{foo + bar} and @samp{foo} are legitimate choices for the sexp to ! 7583: move over if point is at the @samp{f}. Note that @samp{(foo + bar)} is a ! 7584: sexp in C mode. ! 7585: ! 7586: Some languages have obscure forms of syntax for expressions that nobody ! 7587: has bothered to make Emacs understand properly. ! 7588: ! 7589: @c doublewidecommands ! 7590: @table @kbd ! 7591: @item C-M-f ! 7592: Move forward over a sexp (@code{forward-sexp}). ! 7593: @item C-M-b ! 7594: Move backward over a sexp (@code{backward-sexp}). ! 7595: @item C-M-k ! 7596: Kill sexp forward (@code{kill-sexp}). ! 7597: @item C-M-u ! 7598: Move up and backward in list structure (@code{backward-up-list}). ! 7599: @item C-M-d ! 7600: Move down and forward in list structure (@code{down-list}). ! 7601: @item C-M-n ! 7602: Move forward over a list (@code{forward-list}). ! 7603: @item C-M-p ! 7604: Move backward over a list (@code{backward-list}). ! 7605: @item C-M-t ! 7606: Transpose expressions (@code{transpose-sexps}). ! 7607: @item C-M-@@ ! 7608: Put mark after following expression (@code{mark-sexp}). ! 7609: @end table ! 7610: ! 7611: @kindex C-M-f ! 7612: @kindex C-M-b ! 7613: @findex forward-sexp ! 7614: @findex backward-sexp ! 7615: To move forward over a sexp, use @kbd{C-M-f} (@code{forward-sexp}). If ! 7616: the first significant character after point is an opening delimiter ! 7617: (@samp{(} in Lisp; @samp{(}, @samp{[} or @samp{@{} in C), @kbd{C-M-f} ! 7618: moves past the matching closing delimiter. If the character begins a ! 7619: symbol, string, or number, @kbd{C-M-f} moves over that. If the character ! 7620: after point is a closing delimiter, @kbd{C-M-f} just moves past it. (This ! 7621: last is not really moving across a sexp; it is an exception which is ! 7622: included in the definition of @kbd{C-M-f} because it is as useful a ! 7623: behavior as anyone can think of for that situation.)@refill ! 7624: ! 7625: The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a ! 7626: sexp. The detailed rules are like those above for @kbd{C-M-f}, but with ! 7627: directions reversed. If there are any prefix characters (singlequote, ! 7628: backquote and comma, in Lisp) preceding the sexp, @kbd{C-M-b} moves back ! 7629: over them as well. ! 7630: ! 7631: @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the ! 7632: specified number of times; with a negative argument, it moves in the ! 7633: opposite direction. ! 7634: ! 7635: The sexp commands move across comments as if they were whitespace, in ! 7636: languages such as C where the comment-terminator can be recognized. In ! 7637: Lisp, and other languages where comments run until the end of a line, it is ! 7638: very difficult to ignore comments when parsing backwards; therefore, in ! 7639: such languages the sexp commands treat the text of comments as if it were ! 7640: code. ! 7641: ! 7642: @kindex C-M-k ! 7643: @findex kill-sexp ! 7644: Killing a sexp at a time can be done with @kbd{C-M-k} (@code{kill-sexp}). ! 7645: @kbd{C-M-k} kills the characters that @kbd{C-M-f} would move over. ! 7646: ! 7647: @kindex C-M-n ! 7648: @kindex C-M-p ! 7649: @findex forward-list ! 7650: @findex backward-list ! 7651: The @dfn{list commands} move over lists like the sexp commands but skip ! 7652: blithely over any number of other kinds of sexps (symbols, strings, etc). ! 7653: They are @kbd{C-M-n} (@code{forward-list}) and @kbd{C-M-p} ! 7654: (@code{backward-list}). The main reason they are useful is that they ! 7655: usually ignore comments (since the comments usually do not contain any ! 7656: lists).@refill ! 7657: ! 7658: @kindex C-M-u ! 7659: @kindex C-M-d ! 7660: @findex backward-up-list ! 7661: @findex down-list ! 7662: @kbd{C-M-n} and @kbd{C-M-p} stay at the same level in parentheses, when ! 7663: that's possible. To move @i{up} one (or @var{n}) levels, use @kbd{C-M-u} ! 7664: (@code{backward-up-list}). ! 7665: @kbd{C-M-u} moves backward up past one unmatched opening delimiter. A ! 7666: positive argument serves as a repeat count; a negative argument reverses ! 7667: direction of motion and also requests repetition, so it moves forward and ! 7668: up one or more levels.@refill ! 7669: ! 7670: To move @i{down} in list structure, use @kbd{C-M-d} (@code{down-list}). In Lisp mode, ! 7671: where @samp{(} is the only opening delimiter, this is nearly the same as ! 7672: searching for a @samp{(}. An argument specifies the number of levels ! 7673: of parentheses to go down. ! 7674: ! 7675: @cindex transposition ! 7676: @kindex C-M-t ! 7677: @findex transpose-sexps ! 7678: A somewhat random-sounding command which is nevertheless easy to use is ! 7679: @kbd{C-M-t} (@code{transpose-sexps}), which drags the previous sexp across ! 7680: the next one. An argument serves as a repeat count, and a negative ! 7681: argument drags backwards (thus canceling out the effect of @kbd{C-M-t} with ! 7682: a positive argument). An argument of zero, rather than doing nothing, ! 7683: transposes the sexps ending after point and the mark. ! 7684: ! 7685: @kindex C-M-@@ ! 7686: @findex mark-sexp ! 7687: To make the region be the next sexp in the buffer, use @kbd{C-M-@@} ! 7688: (@code{mark-sexp}) which sets mark at the same place that @kbd{C-M-f} would ! 7689: move to. @kbd{C-M-@@} takes arguments like @kbd{C-M-f}. In particular, a ! 7690: negative argument is useful for putting the mark at the beginning of the ! 7691: previous sexp. ! 7692: ! 7693: The list and sexp commands' understanding of syntax is completely ! 7694: controlled by the syntax table. Any character can, for example, be ! 7695: declared to be an opening delimiter and act like an open parenthesis. ! 7696: @xref{Syntax}. ! 7697: ! 7698: @node Defuns, Grinding, Lists, Programs ! 7699: @section Defuns ! 7700: @cindex defuns ! 7701: ! 7702: In Emacs, a parenthetical grouping at the top level in the buffer is ! 7703: called a @dfn{defun}. The name derives from the fact that most top-level ! 7704: lists in a Lisp file are instances of the special form @code{defun}, but ! 7705: any top-level parenthetical grouping counts as a defun in Emacs parlance ! 7706: regardless of what its contents are, and regardless of the programming ! 7707: language in use. For example, in C, the body of a function definition is a ! 7708: defun. ! 7709: ! 7710: @c doublewidecommands ! 7711: @table @kbd ! 7712: @item C-M-a ! 7713: Move to beginning of current or preceding defun ! 7714: (@code{beginning-of-defun}). ! 7715: @item C-M-e ! 7716: Move to end of current or following defun (@code{end-of-defun}). ! 7717: @item C-M-h ! 7718: Put region around whole current or following defun (@code{mark-defun}). ! 7719: @end table ! 7720: ! 7721: @kindex C-M-a ! 7722: @kindex C-M-e ! 7723: @kindex C-M-h ! 7724: @findex beginning-of-defun ! 7725: @findex end-of-defun ! 7726: @findex mark-defun ! 7727: The commands to move to the beginning and end of the current defun are ! 7728: @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e} (@code{end-of-defun}). ! 7729: ! 7730: If you wish to operate on the current defun, use @kbd{C-M-h} ! 7731: (@code{mark-defun}) which puts point at the beginning and mark at the end ! 7732: of the current or next defun. For example, this is the easiest way to get ! 7733: ready to move the defun to a different place in the text. In C mode, ! 7734: @kbd{C-M-h} runs the function @code{mark-c-function}, which is almost the ! 7735: same as @code{mark-defun}; the difference is that it backs up over the ! 7736: argument declarations, function name and returned data type so that the ! 7737: entire C function is inside the region. ! 7738: ! 7739: Emacs assumes that any open-parenthesis found in the leftmost column is ! 7740: the start of a defun. Therefore, @b{never put an open-parenthesis at the ! 7741: left margin in a Lisp file unless it is the start of a top level list. ! 7742: Never put an open-brace or other opening delimiter at the beginning of a ! 7743: line of C code unless it starts the body of a function.} The most likely ! 7744: problem case is when you want an opening delimiter at the start of a line ! 7745: inside a string. To avoid trouble, put an escape character (@samp{\}, in C ! 7746: and Emacs Lisp, @samp{/} in some other Lisp dialects) before the opening ! 7747: delimiter. It will not affect the contents of the string. ! 7748: ! 7749: In the remotest past, the original Emacs found defuns by moving upward a ! 7750: level of parentheses until there were no more levels to go up. This always ! 7751: required scanning all the way back to the beginning of the buffer, even for ! 7752: a small function. To speed up the operation, Emacs was changed to assume ! 7753: that any @samp{(} (or other character assigned the syntactic class of ! 7754: opening-delimiter) at the left margin is the start of a defun. This ! 7755: heuristic was nearly always right and avoided the costly scan; however, ! 7756: it mandated the convention described above. ! 7757: ! 7758: @node Grinding, Matching, Defuns, Programs ! 7759: @section Indentation for Programs ! 7760: @cindex indentation ! 7761: @cindex grinding ! 7762: ! 7763: The best way to keep a program properly indented (``ground'') is to use ! 7764: Emacs to re-indent it as you change it. Emacs has commands to indent ! 7765: properly either a single line, a specified number of lines, or all of the ! 7766: lines inside a single parenthetical grouping. ! 7767: ! 7768: @menu ! 7769: * Basic Indent:: ! 7770: * Multi-line Indent:: Commands to reindent many lines at once. ! 7771: * Lisp Indent:: Specifying how each Lisp function should be indented. ! 7772: * C Indent:: Choosing an indentation style for C code. ! 7773: @end menu ! 7774: ! 7775: @node Basic Indent, Multi-line Indent, Grinding, Grinding ! 7776: @subsection Basic Program Indentation Commands ! 7777: ! 7778: @c WideCommands ! 7779: @table @kbd ! 7780: @item @key{TAB} ! 7781: Adjust indentation of current line. ! 7782: @item @key{LFD} ! 7783: Equivalent to @key{RET} followed by @key{TAB} (@code{newline-and-indent}). ! 7784: @end table ! 7785: ! 7786: @kindex TAB ! 7787: @findex c-indent-line ! 7788: @findex lisp-indent-line ! 7789: The basic indentation command is @key{TAB}, which gives the current line ! 7790: the correct indentation as determined from the previous lines. The ! 7791: function that @key{TAB} runs depends on the major mode; it is @code{lisp-indent-line} ! 7792: in Lisp mode, @code{c-indent-line} in C mode, etc. These functions ! 7793: understand different syntaxes for different languages, but they all do ! 7794: about the same thing. @key{TAB} in any programming language major mode ! 7795: inserts or deletes whitespace at the beginning of the current line, ! 7796: independent of where point is in the line. If point is inside the ! 7797: whitespace at the beginning of the line, @key{TAB} leaves it at the end of ! 7798: that whitespace; otherwise, @key{TAB} leaves point fixed with respect to ! 7799: the characters around it. ! 7800: ! 7801: Use @kbd{C-q @key{TAB}} to insert a tab at point. ! 7802: ! 7803: @kindex LFD ! 7804: @findex newline-and-indent ! 7805: When entering a large amount of new code, use @key{LFD} (@code{newline-and-indent}), ! 7806: which is equivalent to a @key{RET} followed by a @key{TAB}. @key{LFD} creates ! 7807: a blank line, and then gives it the appropriate indentation. ! 7808: ! 7809: @key{TAB} indents the second and following lines of the body of an ! 7810: parenthetical grouping each under the preceding one; therefore, if you ! 7811: alter one line's indentation to be nonstandard, the lines below will tend ! 7812: to follow it. This is the right behavior in cases where the standard ! 7813: result of @key{TAB} is unaesthetic. ! 7814: ! 7815: Remember that an open-parenthesis, open-brace or other opening delimiter ! 7816: at the left margin is assumed by Emacs (including the indentation routines) ! 7817: to be the start of a function. Therefore, you must never have an opening ! 7818: delimiter in column zero that is not the beginning of a function, not even ! 7819: inside a string. This restriction is vital for making the indentation ! 7820: commands fast; you must simply accept it. @xref{Defuns}, for more ! 7821: information on this. ! 7822: ! 7823: @node Multi-line Indent, Lisp Indent, Basic Indent, Grinding ! 7824: @subsection Indenting Several Lines ! 7825: ! 7826: When you wish to re-indent several lines of code which have been altered ! 7827: or moved to a different level in the list structure, you have several ! 7828: commands available. ! 7829: ! 7830: @table @kbd ! 7831: @item C-M-q ! 7832: Re-indent all the lines within one list (@code{indent-sexp}). ! 7833: @item C-u @key{TAB} ! 7834: Shift an entire list rigidly sideways so that its first line ! 7835: is properly indented. ! 7836: @item C-M-\ ! 7837: Re-indent all lines in the region (@code{indent-region}). ! 7838: @end table ! 7839: ! 7840: @kindex C-M-q ! 7841: @findex indent-sexp ! 7842: @findex indent-c-exp ! 7843: You can re-indent the contents of a single list by positioning point ! 7844: before the beginning of it and typing @kbd{C-M-q} (@code{indent-sexp} in ! 7845: Lisp mode, @code{indent-c-exp} in C mode; also bound to other suitable ! 7846: functions in other modes). The indentation of the line the sexp starts on ! 7847: is not changed; therefore, only the relative indentation within the list, ! 7848: and not its position, is changed. To correct the position as well, type a ! 7849: @key{TAB} before the @kbd{C-M-q}. ! 7850: ! 7851: @kindex C-u TAB ! 7852: If the relative indentation within a list is correct but the indentation ! 7853: of its beginning is not, go to the line the list begins on and type ! 7854: @kbd{C-u @key{TAB}}. When @key{TAB} is given a numeric argument, it moves all the ! 7855: lines in the grouping starting on the current line sideways the same amount ! 7856: that the current line moves. It is clever, though, and does not move lines ! 7857: that start inside strings, or C preprocessor lines when in C mode. ! 7858: ! 7859: @kindex C-M-\ ! 7860: @findex indent-region ! 7861: Another way to specify the range to be re-indented is with point and ! 7862: mark. The command @kbd{C-M-\} (@code{indent-region}) applies @key{TAB} to every line ! 7863: whose first character is between point and mark. ! 7864: ! 7865: @node Lisp Indent, C Indent, Multi-line Indent, Grinding ! 7866: @subsection Customizing Lisp Indentation ! 7867: @cindex customization ! 7868: ! 7869: The indentation pattern for a Lisp expression can depend on the function ! 7870: called by the expression. For each Lisp function, you can choose among ! 7871: several predefined patterns of indentation, or define an arbitrary one with ! 7872: a Lisp program. ! 7873: ! 7874: The standard pattern of indentation is as follows: the second line of the ! 7875: expression is indented under the first argument, if that is on the same ! 7876: line as the beginning of the expression; otherwise, the second line is ! 7877: indented underneath the function name. Each following line is indented ! 7878: under the previous line whose nesting depth is the same. ! 7879: ! 7880: @vindex lisp-indent-offset ! 7881: If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides ! 7882: the usual indentation pattern for the second line of an expression, so that ! 7883: such lines are always indented @code{lisp-indent-offset} more columns than ! 7884: the containing list. ! 7885: ! 7886: @vindex lisp-body-indention ! 7887: The standard pattern is overridded for certain functions. Functions ! 7888: whose names start with @code{def} always indent the second line by ! 7889: @code{lisp-body-indention} extra columns beyond the open-parenthesis ! 7890: starting the expression. ! 7891: ! 7892: The standard pattern can be overridden in various ways for individual ! 7893: functions, according to the @code{lisp-indent-hook} property of the ! 7894: function name. There are four possibilities for this property: ! 7895: ! 7896: @table @asis ! 7897: @item @code{nil} ! 7898: This is the same as no property; the standard indentation pattern is used. ! 7899: @item @code{defun} ! 7900: The pattern used for function names that start with @code{def} is used for ! 7901: this function also. ! 7902: @item a number, @var{number} ! 7903: The first @var{number} arguments of the function are ! 7904: @dfn{distinguished} arguments; the rest are considered the @dfn{body} ! 7905: of the expression. A line in the expression is indented according to ! 7906: whether the first argument on it is distinguished or not. If the ! 7907: argument is part of the body, the line is indented @code{lisp-body-indent} ! 7908: more columns than the open-parenthesis starting the containing ! 7909: expression. If the argument is distinguished and is either the first ! 7910: or second argument, it is indented @i{twice} that many extra columns. ! 7911: If the argument is distinguished and not the first or second argument, ! 7912: the standard pattern is followed for that line. ! 7913: @item a symbol, @var{symbol} ! 7914: @var{symbol} should be a function name; that function is called to ! 7915: calculate the indentation of a line within this expression. The ! 7916: function receives two arguments: ! 7917: @table @asis ! 7918: @item @var{state} ! 7919: The value returned by @code{parse-partial-sexp} (a Lisp primitive for ! 7920: indentation and nesting computation) when it parses up to the ! 7921: beginning of this line. ! 7922: @item @var{pos} ! 7923: The position at which the line being indented begins. ! 7924: @end table ! 7925: @noindent ! 7926: It should return either a number, which is the number of columns of ! 7927: indentation for that line, or a list whose car is such a number. The ! 7928: difference between returning a number and returning a list is that a ! 7929: number says that all following lines at the same nesting level should ! 7930: be indented just like this one; a list says that following lines might ! 7931: call for different indentations. This makes a difference when the ! 7932: indentation is being computed by @kbd{C-M-q}; if the value is a ! 7933: number, @kbd{C-M-q} need not recalculate indentation for the following ! 7934: lines until the end of the list. ! 7935: @end table ! 7936: ! 7937: @node C Indent,, Lisp Indent, Grinding ! 7938: @subsection Customizing C Indentation ! 7939: ! 7940: Two variables control which commands perform C indentation and when. ! 7941: ! 7942: @vindex c-auto-newline ! 7943: If @code{c-auto-newline} is non-@code{nil}, newlines are inserted both ! 7944: before and after braces that you insert, and after colons and semicolons. ! 7945: Correct C indentation is done on all the lines that are made this way. ! 7946: ! 7947: @vindex c-tab-always-indent ! 7948: If @code{c-tab-always-indent} is non-@code{nil}, the @key{TAB} command ! 7949: in C mode does indentation only if point is at the left margin or within ! 7950: the line's indentation. If there is non-whitespace to the left of point, ! 7951: then @key{TAB} just inserts a tab character in the buffer. Normally, ! 7952: this variable is @code{nil}, and @key{TAB} always reindents the current line. ! 7953: ! 7954: C does not have anything analogous to particular function names for which ! 7955: special forms of indentation are desirable. However, it has a different ! 7956: need for customization facilities: many different styles of C indentation ! 7957: are in common use. ! 7958: ! 7959: There are six variables you can set to control the style that Emacs C ! 7960: mode will use. ! 7961: ! 7962: @table @code ! 7963: @item c-indent-level ! 7964: Indentation of C statements within surrounding block. The surrounding ! 7965: block's indentation is the indentation of the line on which the ! 7966: open-brace appears. ! 7967: @item c-continued-statement-offset ! 7968: Extra indentation given to a substatement, such as the then-clause of ! 7969: an if or body of a while. ! 7970: @item c-brace-offset ! 7971: Extra indentation for line if it starts with an open brace. ! 7972: @item c-brace-imaginary-offset ! 7973: An open brace following other text is treated as if it were this far ! 7974: to the right of the start of its line. ! 7975: @item c-argdecl-indent ! 7976: Indentation level of declarations of C function arguments. ! 7977: @item c-label-offset ! 7978: Extra indentation for line that is a label, or case or default. ! 7979: @end table ! 7980: ! 7981: @vindex c-indent-level ! 7982: The variable @code{c-indent-level} controls the indentation for C ! 7983: statements with respect to the surrounding block. In the example ! 7984: ! 7985: @example ! 7986: @{ ! 7987: foo (); ! 7988: @end example ! 7989: ! 7990: @noindent ! 7991: the difference in indentation between the lines is @code{c-indent-level}. ! 7992: Its standard value is 2. ! 7993: ! 7994: If the open-brace beginning the compound statement is not at the beginning ! 7995: of its line, the @code{c-indent-level} is added to the indentation of the ! 7996: line, not the column of the open-brace. For example, ! 7997: ! 7998: @example ! 7999: if (losing) @{ ! 8000: do_this (); ! 8001: @end example ! 8002: ! 8003: @noindent ! 8004: One popular indentation style is that which results from setting ! 8005: @code{c-indent-level} to 8 and putting open-braces at the end of a line in ! 8006: this way. I prefer to put the open-brace on a separate line. ! 8007: ! 8008: @vindex c-brace-imaginary-offset ! 8009: In fact, the value of the variable @code{c-brace-imaginary-offset} is ! 8010: also added to the indentation of such a statement. Normally this variable ! 8011: is zero. Think of this variable as the imaginary position of the open ! 8012: brace, relative to the first nonblank character on the line. By setting ! 8013: this variable to 4 and @code{c-indent-level} to 0, you can get this style: ! 8014: ! 8015: @example ! 8016: if (x == y) @{ ! 8017: do_it (); ! 8018: @} ! 8019: @end example ! 8020: ! 8021: When @code{c-indent-level} is zero, the statements inside most braces ! 8022: will line up right under the open brace. But there is an exception made ! 8023: for braces in column zero, such as surrounding a function's body. The ! 8024: statements just inside it do not go at column zero. Instead, ! 8025: @code{c-brace-offset} and @code{c-continued-statement-offset} (see below) ! 8026: are added to produce a typical offset between brace levels, and the ! 8027: statements are indented that far. ! 8028: ! 8029: @vindex c-continued-statement-offset ! 8030: @code{c-continued-statement-offset} controls the extra indentation for a ! 8031: line that starts within a statement (but not within parentheses or ! 8032: brackets). These lines are usually statements that are within other ! 8033: statements, such as the then-clauses of @code{if} statements and the bodies ! 8034: of @code{while} statements. This parameter is the difference in ! 8035: indentation between the two lines in ! 8036: ! 8037: @example ! 8038: if (x == y) ! 8039: do_it (); ! 8040: @end example ! 8041: ! 8042: @noindent ! 8043: Its standard value is 2. Some popular indentation styles correspond to a ! 8044: value of zero for @code{c-continued-statement-offset}. ! 8045: ! 8046: @vindex c-brace-offset ! 8047: @code{c-brace-offset} is the extra indentation given to a line that ! 8048: starts with an open-brace. Its standard value is zero; ! 8049: compare ! 8050: ! 8051: @example ! 8052: if (x == y) ! 8053: @{ ! 8054: @end example ! 8055: ! 8056: @noindent ! 8057: with ! 8058: ! 8059: @example ! 8060: if (x == y) ! 8061: do_it (); ! 8062: @end example ! 8063: ! 8064: @noindent ! 8065: if @code{c-brace-offset} were set to 4, the first example would become ! 8066: ! 8067: @example ! 8068: if (x == y) ! 8069: @{ ! 8070: @end example ! 8071: ! 8072: @vindex c-argdecl-indent ! 8073: @code{c-argdecl-indent} controls the indentation of declarations of the ! 8074: arguments of a C function. It is absolute: argument declarations receive ! 8075: exactly @code{c-argdecl-indent} spaces. The standard value is 5, resulting ! 8076: in code like this: ! 8077: ! 8078: @example ! 8079: char * ! 8080: index (string, char) ! 8081: char *string; ! 8082: int char; ! 8083: @end example ! 8084: ! 8085: @vindex c-label-offset ! 8086: @code{c-label-offset} is the extra indentation given to a line that ! 8087: contains a label, a case statement, or a @code{default:} statement. Its ! 8088: standard value is @minus{}2, resulting in code like this ! 8089: ! 8090: @example ! 8091: switch (c) ! 8092: @{ ! 8093: case 'x': ! 8094: @end example ! 8095: ! 8096: @noindent ! 8097: If @code{c-label-offset} were zero, the same code would be indented as ! 8098: ! 8099: @example ! 8100: switch (c) ! 8101: @{ ! 8102: case 'x': ! 8103: @end example ! 8104: ! 8105: @noindent ! 8106: This example assumes that the other variables above also have their ! 8107: standard values. ! 8108: ! 8109: I strongly recommend that you try out the indentation style produced by ! 8110: the standard settings of these variables, together with putting open braces ! 8111: on separate lines. You can see how it looks in all the C source files of ! 8112: GNU Emacs. ! 8113: ! 8114: @node Matching, Comments, Grinding, Programs ! 8115: @section Automatic Display Of Matching Parentheses ! 8116: @cindex matching parentheses ! 8117: @cindex parentheses ! 8118: ! 8119: The Emacs parenthesis-matching feature is designed to show automatically ! 8120: how parentheses match in the text. Whenever a self-inserting character ! 8121: that is a closing delimiter is typed, the cursor moves momentarily to the ! 8122: location of the matching opening delimiter, provided that is on the screen. ! 8123: If it is not on the screen, some text starting with that opening delimiter ! 8124: is displayed in the echo area. Either way, you can tell what grouping is ! 8125: being closed off. ! 8126: ! 8127: In Lisp, automatic matching applies only to parentheses. In C, it ! 8128: applies to braces and brackets too. Emacs knows which characters to regard ! 8129: as matching delimiters based on the syntax table, which is set by the major ! 8130: mode. @xref{Syntax}. ! 8131: ! 8132: If the opening delimiter and closing delimiter are mismatched---such as ! 8133: in @samp{[x)}---a warning message is displayed in the echo area. The ! 8134: correct matches are specified in the syntax table. ! 8135: ! 8136: @vindex blink-matching-paren ! 8137: @vindex blink-matching-paren-distance ! 8138: Two variables control parenthesis match display. @code{blink-matching-paren} ! 8139: turns the feature on or off; @code{nil} turns it off, but the default is ! 8140: @code{t} to turn match display on. @code{blink-matching-paren-distance} ! 8141: specifies how many characters back to search to find the matching opening ! 8142: delimiter. If the match is not found in that far, scanning stops, and ! 8143: nothing is displayed. This is to prevent scanning for the matching ! 8144: delimiter from wasting lots of time when there is no match. The default ! 8145: is 4000. ! 8146: ! 8147: @node Comments, Balanced Editing, Matching, Programs ! 8148: @section Manipulating Comments ! 8149: @cindex comments ! 8150: @kindex M-; ! 8151: @cindex indentation ! 8152: @findex indent-for-comment ! 8153: ! 8154: The comment commands insert, kill and align comments. ! 8155: ! 8156: @c WideCommands ! 8157: @table @kbd ! 8158: @item M-; ! 8159: Insert or align comment (@code{indent-for-comment}). ! 8160: @item C-x ; ! 8161: Set comment column (@code{set-comment-column}). ! 8162: @item C-u - C-x ; ! 8163: Kill comment on current line (@code{kill-comment}). ! 8164: @item M-@key{LFD} ! 8165: Like @key{RET} followed by inserting and aligning a comment ! 8166: (@code{indent-new-comment-line}). ! 8167: @end table ! 8168: ! 8169: The command that creates a comment is @kbd{Meta-;} (@code{indent-for-comment}). ! 8170: If there is no comment already on the line, a new comment is created, ! 8171: aligned at a specific column called the @dfn{comment column}. The comment ! 8172: is created by inserting the string Emacs thinks comments should start with ! 8173: (the value of @code{comment-start}; see below). Point is left after that ! 8174: string. If the text of the line extends past the comment column, then the ! 8175: indentation is done to a suitable boundary (usually, at least one space is ! 8176: inserted). If the major mode has specified a string to terminate comments, ! 8177: that is inserted after point, to keep the syntax valid. ! 8178: ! 8179: @kbd{Meta-;} can also be used to align an existing comment. If a line ! 8180: already contains the string that starts comments, then @kbd{M-;} just moves ! 8181: point after it and re-indents it to the conventional place. Exception: ! 8182: comments starting in column 0 are not moved. ! 8183: ! 8184: Some major modes have special rules for indenting certain kinds of ! 8185: comments in certain contexts. For example, in Lisp code, comments which ! 8186: start with two semicolons are indented as if they were lines of code, ! 8187: instead of at the comment column. Comments which start with three ! 8188: semicolons are supposed to start at the left margin. Emacs understands ! 8189: these conventions by indenting a double-semicolon comment using @key{TAB}, ! 8190: and by not changing the indentation of a triple-semicolon comment at all. ! 8191: ! 8192: @example ! 8193: ;; This function is just an example ! 8194: ;;; Here either two or three semicolons are appropriate. ! 8195: (defun foo (x) ! 8196: ;;; And now, the first part of the function: ! 8197: ;; The following line adds one. ! 8198: (1+ x)) ; This line adds one. ! 8199: @end example ! 8200: ! 8201: In C code, a comment preceded on its line by nothing but whitespace ! 8202: is indented like a line of code. ! 8203: ! 8204: Even when an existing comment is properly aligned, @kbd{M-;} is still ! 8205: useful for moving directly to the start of the comment. ! 8206: ! 8207: @kindex C-u - C-x ; ! 8208: @findex kill-comment ! 8209: @kbd{C-u - C-x ;} (@code{kill-comment}) kills the comment on the current line, ! 8210: if there is one. The indentation before the start of the comment is killed ! 8211: as well. If there does not appear to be a comment in the line, nothing is ! 8212: done. To reinsert the comment on another line, move to the end of that ! 8213: line, do @kbd{C-y}, and then do @kbd{M-;} to realign it. Note that ! 8214: @kbd{C-u - C-x ;} is not a distinct key; it is @kbd{C-x ;} (@code{set-comment-column}) ! 8215: with a negative argument. That command is programmed so that when it ! 8216: receives a negative argument it calls @code{kill-comment}. However, ! 8217: @code{kill-comment} is a valid command which you could bind directly to a ! 8218: key if you wanted to. ! 8219: ! 8220: @subsection Multiple Lines of Comments ! 8221: ! 8222: @kindex M-LFD ! 8223: @cindex blank lines ! 8224: @cindex Auto Fill mode ! 8225: @findex indent-new-comment-line ! 8226: If you are typing a comment and find that you wish to continue it on ! 8227: another line, you can use the command @kbd{Meta-@key{LFD}} (@code{indent-new-comment-line}), ! 8228: which terminates the comment you are typing, creates a new blank line ! 8229: afterward, and begins a new comment indented under the old one. When Auto ! 8230: Fill mode is on, going past the fill column while typing a comment causes ! 8231: the comment to be continued in just this fashion. If point is not at the ! 8232: end of the line when @kbd{M-@key{LFD}} is typed, the text on the rest of ! 8233: the line becomes part of the new comment line. ! 8234: ! 8235: @subsection Options Controlling Comments ! 8236: ! 8237: @vindex comment-column ! 8238: @kindex C-x ; ! 8239: @findex set-comment-column ! 8240: The comment column is stored in the variable @code{comment-column}. You ! 8241: can set it to a number explicitly. Alternatively, the command @kbd{C-x ;} ! 8242: (@code{set-comment-column}) sets the comment column to the column point is ! 8243: at. @kbd{C-u C-x ;} sets the comment column to match the last comment ! 8244: before point in the buffer, and then does a @kbd{Meta-;} to align the ! 8245: current line's comment under the previous one. Note that @kbd{C-u - C-x ;} ! 8246: runs the function @code{kill-comment} as described above. ! 8247: ! 8248: @code{comment-column} is a per-buffer variable; altering the variable ! 8249: affects only the current buffer, but there is a default value which you can ! 8250: change as well. @xref{Locals}. Many major modes initialize this variable ! 8251: for the current buffer. ! 8252: ! 8253: @vindex comment-start-skip ! 8254: The comment commands recognize comments based on the regular expression ! 8255: that is the value of the variable @code{comment-start-skip}. This regexp ! 8256: should not match the null string. It may match more than the comment ! 8257: starting delimiter in the strictest sense of the word; for example, in C ! 8258: mode the value of the variable is @code{@t{"/\\*+ *"}}, which matches extra ! 8259: stars and spaces after the @samp{/*} itself. (Note that @samp{\\} is ! 8260: needed in Lisp syntax to include a @samp{\} in the string, which is needed ! 8261: to deny the first star its special meaning in regexp syntax. @xref{Regexps}.) ! 8262: ! 8263: @vindex comment-start ! 8264: @vindex comment-end ! 8265: When a comment command makes a new comment, it inserts the value of ! 8266: @code{comment-start} to begin it. The value of @code{comment-end} is ! 8267: inserted after point, so that it will follow the text that you will insert ! 8268: into the comment. In C mode, @code{comment-start} has the value ! 8269: @w{@code{"/* "}} and @code{comment-end} has the value @w{@code{" */"}}. ! 8270: ! 8271: @vindex comment-multi-line ! 8272: @code{comment-multi-line} controls how @kbd{M-@key{LFD}} (@code{indent-new-comment-line}) ! 8273: behaves when used inside a comment. If @code{comment-multi-line} is ! 8274: @code{nil}, as it normally is, then the comment on the starting line is ! 8275: terminated and a new comment is started on the new following line. If ! 8276: @code{comment-multi-line} is not @code{nil}, then the new following line is ! 8277: set up as part of the same comment that was found on the starting line. ! 8278: This is done by not inserting a terminator on the old line, and not ! 8279: inserting a starter on the new line. In languages where multi-line comments ! 8280: work, the choice of value for this variable is a matter of taste. ! 8281: ! 8282: @vindex comment-indent-hook ! 8283: The variable @code{comment-indent-hook} should contain a function that ! 8284: will be called to compute the indentation for a newly inserted comment or ! 8285: for aligning an existing comment. It is set differently by various major ! 8286: modes. The function is called with no arguments, but with point at the ! 8287: beginning of the comment, or at the end of a line if a new comment is to be ! 8288: inserted. It should return the column in which the comment ought to start. ! 8289: For example, in Lisp mode, the indent hook function bases its decision ! 8290: on how many semicolons begin an existing comment, and on the code in the ! 8291: preceding lines. ! 8292: ! 8293: @node Balanced Editing, Lisp Completion, Comments, Programs ! 8294: @section Editing Without Unbalanced Parentheses ! 8295: ! 8296: @table @kbd ! 8297: @item M-( ! 8298: Put parentheses around next sexp(s) (@code{insert-parentheses}). ! 8299: @item M-) ! 8300: Move past next close parenthesis and re-indent ! 8301: (@code{move-over-close-and-reindent}). ! 8302: @end table ! 8303: ! 8304: @kindex M-( ! 8305: @kindex M-) ! 8306: @findex insert-parentheses ! 8307: @findex move-over-close-and-reindent ! 8308: The commands @kbd{M-(} (@code{insert-parentheses}) and @kbd{M-)} ! 8309: (@code{move-over-close-and-reindent}) are designed to facilitate a style of ! 8310: editing which keeps parentheses balanced at all times. @kbd{M-(} inserts a ! 8311: pair of parentheses, either together as in @samp{()}, or, if given an ! 8312: argument, around the next several sexps, and leaves point after the open ! 8313: parenthesis. Instead of typing @kbd{( F O O )}, you can type @kbd{M-( F O ! 8314: O}, which has the same effect except for leaving the cursor before the ! 8315: close parenthesis. Then you would type @kbd{M-)}, which moves past the ! 8316: close parenthesis, deleting any indentation preceding it (in this example ! 8317: there is none), and indenting with @key{LFD} after it. ! 8318: ! 8319: @node Lisp Completion, Documentation, Balanced Editing, Programs ! 8320: @section Completion for Lisp Symbols ! 8321: @cindex completion (symbol names) ! 8322: ! 8323: Usually completion happens in the minibuffer. But one kind of completion ! 8324: is available in all buffers: completion for Lisp symbol names. ! 8325: ! 8326: @kindex M-TAB ! 8327: @findex lisp-complete-symbol ! 8328: The command @kbd{M-@key{TAB}} (@code{lisp-complete-symbol}) takes the ! 8329: partial Lisp symbol before point to be an abbreviation, and compares it ! 8330: against all nontrivial Lisp symbols currently known to Emacs. Any ! 8331: additional characters that they all have in common are inserted at point. ! 8332: Nontrivial symbols are those that have function definitions, values or ! 8333: properties. ! 8334: ! 8335: If there is an open-parenthesis immediately before the beginning of ! 8336: the partial symbol, only symbols with function definitions are considered ! 8337: as completions. ! 8338: ! 8339: If the partial name in the buffer has more than one possible completion ! 8340: and they have no additional characters in common, a list of all possible ! 8341: completions is displayed in another window. ! 8342: ! 8343: @node Documentation, Change Log, Lisp Completion, Programs ! 8344: @section Documentation Commands ! 8345: ! 8346: @kindex C-h f ! 8347: @findex describe-function ! 8348: @kindex C-h v ! 8349: @findex describe-variable ! 8350: As you edit Lisp code to be run in Emacs, the commands @kbd{C-h f} ! 8351: (@code{describe-function}) and @kbd{C-h v} (@code{describe-variable}) can ! 8352: be used to print documentation of functions and variables that you want to ! 8353: call. These commands use the minibuffer to read the name of a function or ! 8354: variable to document, and display the documentation in a window. ! 8355: ! 8356: For extra convenience, these commands provide default arguments based on ! 8357: the code in the neighborhood of point. @kbd{C-h f} sets the default to the ! 8358: function called in the innermost list containing point. @kbd{C-h v} uses ! 8359: the symbol name around or adjacent to point as its default. ! 8360: ! 8361: @findex manual-entry ! 8362: Documentation on Unix commands, system calls and libraries can be ! 8363: obtained with the @kbd{M-x manual-entry} command. This reads a topic as an ! 8364: argument, and displays the text on that topic from the Unix manual. ! 8365: @code{manual-entry} always searches all 8 sections of the manual, and ! 8366: concatenates all the entries that are found. For example, the topic ! 8367: @samp{termcap} finds the description of the termcap library from section 3, ! 8368: followed by the description of the termcap data base from section 5. ! 8369: ! 8370: @node Change Log, Tags, Documentation, Programs ! 8371: @section Change Logs ! 8372: ! 8373: @cindex change log ! 8374: @findex add-change-log-entry ! 8375: The Emacs command @kbd{M-x add-change-log-entry} helps you keep a record ! 8376: of when and why you have changed a program. It assumes that you have a ! 8377: file in which you write a chronological sequence of entries describing ! 8378: individual changes. The default is to store the change entries in a file ! 8379: called @file{ChangeLog} in the same directory as the file you are editing. ! 8380: The same @file{ChangeLog} file therefore records changes for all the files ! 8381: in the directory. ! 8382: ! 8383: A change log entry starts with a header line that contains your name and ! 8384: the current date. Aside from these header lines, every line in the change ! 8385: log starts with a tab. One entry can describe several changes; each change ! 8386: starts with a line starting with a tab and a star. @kbd{M-x add-change-log-entry} ! 8387: visits the change log file and creates a new entry unless the most recent ! 8388: entry is for today's date and your name. In either case, it adds a new ! 8389: line to start the description of another change just after the header line ! 8390: of the entry. When @kbd{M-x add-change-log-entry} is finished, all is ! 8391: prepared for you to edit in the description of what you changed and how. ! 8392: You must then save the change log file yourself. ! 8393: ! 8394: The change log file is always visited in Indented Text mode, which means ! 8395: that @key{LFD} and auto-filling indent each new line like the previous ! 8396: line. This is convenient for entering the contents of an entry, which must ! 8397: all be indented. @xref{Text Mode}. ! 8398: ! 8399: Here is an example of the formatting conventions used in the change log ! 8400: for Emacs: ! 8401: ! 8402: @smallexample ! 8403: Wed Jun 26 19:29:32 1985 Richard M. Stallman (rms at mit-prep) ! 8404: ! 8405: * xdisp.c (try_window_id): ! 8406: If C-k is done at end of next-to-last line, ! 8407: this fn updates window_end_vpos and cannot leave ! 8408: window_end_pos nonnegative (it is zero, in fact). ! 8409: If display is preempted before lines are output, ! 8410: this is inconsistent. Fix by setting ! 8411: blank_end_of_window to nonzero. ! 8412: ! 8413: Tue Jun 25 05:25:33 1985 Richard M. Stallman (rms at mit-prep) ! 8414: ! 8415: * cmds.c (Fnewline): ! 8416: Call the auto fill hook if appropriate. ! 8417: ! 8418: * xdisp.c (try_window_id): ! 8419: If point is found by compute_motion after xp, record that ! 8420: permanently. If display_text_line sets point position wrong ! 8421: (case where line is killed, point is at eob and that line is ! 8422: not displayed), set it again in final compute_motion. ! 8423: @end smallexample ! 8424: ! 8425: @node Tags, Fortran, Change Log, Programs ! 8426: @section Tag Tables ! 8427: @cindex tag table ! 8428: ! 8429: A @dfn{tag table} is a description of how a multi-file program is broken ! 8430: up into files. It lists the names of the component files and the names and ! 8431: positions of the functions in each file. Grouping the related files makes ! 8432: it possible to search or replace through all the files with one command. ! 8433: Recording the function names and positions makes possible the @kbd{Meta-.} ! 8434: command which you can use to find the definition of a function without ! 8435: having to know which of the files it is in. ! 8436: ! 8437: Tag tables are stored in files called @dfn{tag table files}. The ! 8438: conventional name for a tag table file is @file{TAGS}. ! 8439: ! 8440: Each entry in the tag table records the name of one tag, the name of the ! 8441: file that the tag is defined in (implicitly), and the position in that file ! 8442: of the tag's definition. ! 8443: ! 8444: Just what names from the described files are recorded in the tag table ! 8445: depends on the programming language of the described file. They normally ! 8446: include all functions and subroutines, and may also include global ! 8447: variables, data types, and anything else convenient. In any case, each ! 8448: name recorded is called a @dfn{tag}. ! 8449: ! 8450: @menu ! 8451: * Tag Syntax:: ! 8452: * Create Tag Table:: ! 8453: * Select Tag Table:: ! 8454: * Find Tag:: ! 8455: * Tags Search:: ! 8456: * Tags Stepping:: ! 8457: * List Tags:: ! 8458: @end menu ! 8459: ! 8460: @node Tag Syntax, Create Tag Table, Tags, Tags ! 8461: @subsection Source File Tag Syntax ! 8462: ! 8463: In Lisp code, any function defined with @code{defun}, any variable ! 8464: defined with @code{defvar} or @code{defconst}, and in general the first ! 8465: argument of any expression that starts with @samp{(def} in column zero, is ! 8466: a tag. ! 8467: ! 8468: In C code, any C function is a tag, and so is any typedef if @code{-t} is ! 8469: specified when the tag table is constructed. ! 8470: ! 8471: In Fortran code, functions and subroutines are tags. ! 8472: ! 8473: In La@TeX{} text, the argument of any of the commands @code{\chapter}, ! 8474: @code{\section}, @code{\subsection}, @code{\subsubsection}, @code{\eqno}, ! 8475: @code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem} and ! 8476: @code{\typeout} is a tag.@refill ! 8477: ! 8478: @node Create Tag Table, Select Tag Table, Tag Syntax, Tags ! 8479: @subsection Creating Tag Tables ! 8480: @cindex etags program ! 8481: ! 8482: The @code{etags} program is used to create a tag table file. It knows ! 8483: the syntax of C, Fortran, La@TeX{}, Scheme and Emacs Lisp/Common Lisp. To ! 8484: use @code{etags}, type ! 8485: ! 8486: @example ! 8487: etags @var{inputfiles}@dots{} ! 8488: @end example ! 8489: ! 8490: @noindent ! 8491: as a shell command. It reads the specified files and writes a tag table ! 8492: named @file{TAGS} in the current working directory. @code{etags} ! 8493: recognizes the language used in an input file based on its file name and ! 8494: contents; there are no switches for specifying the language. The @code{-t} ! 8495: switch tells @code{etags} to record typedefs in C code as tags. ! 8496: ! 8497: If the tag table data become outdated due to changes in the files ! 8498: described in the table, the way to update the tag table is the same way it ! 8499: was made in the first place. It is not necessary to do this often. ! 8500: ! 8501: If the tag table fails to record a tag, or records it for the wrong file, ! 8502: then Emacs cannot possibly find its definition. However, if the position ! 8503: recorded in the tag table becomes a little bit wrong (due to some editing ! 8504: in the file that the tag definition is in), the only consequence is to slow ! 8505: down finding the tag slightly. Even if the stored position is very wrong, ! 8506: Emacs will still find the tag, but it must search the entire file for it. ! 8507: ! 8508: So you should update a tag table when you define new tags that you want ! 8509: to have listed, or when you move tag definitions from one file to another, ! 8510: or when changes become substantial. Normally there is no need to update ! 8511: the tag table after each edit, or even every day. ! 8512: ! 8513: @node Select Tag Table, Find Tag, Create Tag Table, Tags ! 8514: @subsection Selecting a Tag Table ! 8515: ! 8516: @vindex tags-file-name ! 8517: @findex visit-tags-table ! 8518: Emacs has at any time one @dfn{selected} tag table, and all the commands ! 8519: for working with tag tables use the selected one. To select a tag table, ! 8520: type @kbd{M-x visit-tags-table}, which reads the tag table file name as an ! 8521: argument. The name @file{TAGS} in the default directory is used as the ! 8522: default file name. ! 8523: ! 8524: All this command does is store the file name in the variable ! 8525: @code{tags-file-name}. Emacs does not actually read in the tag table ! 8526: contents until you try to use them. Setting this variable yourself is just ! 8527: as good as using @code{visit-tags-table}. The variable's initial value is ! 8528: @code{nil}; this value tells all the commands for working with tag tables ! 8529: that they must ask for a tag table file name to use. ! 8530: ! 8531: @node Find Tag, Tags Search, Select Tag Table, Tags ! 8532: @subsection Finding a Tag ! 8533: ! 8534: The most important thing that a tag table enables you to do is to find ! 8535: the definition of a specific tag. ! 8536: ! 8537: @table @kbd ! 8538: @item M-.@: @var{tag} ! 8539: Find first definition of @var{tag} (@code{find-tag}). ! 8540: @item C-u M-. ! 8541: Find next alternate definition of last tag specified. ! 8542: @item C-x 4 .@: @var{tag} ! 8543: Find first definition of @var{tag}, but display it in another window ! 8544: (@code{find-tag-other-window}). ! 8545: @end table ! 8546: ! 8547: @kindex M-. ! 8548: @findex find-tag ! 8549: @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of a ! 8550: specified tag. It searches through the tag table for that tag, as a ! 8551: string, and then uses the tag table info to determine the file that the ! 8552: definition is in and the approximate character position in the file of the ! 8553: definition. Then @code{find-tag} visits that file, moves point to the ! 8554: approximate character position, and starts searching ever-increasing ! 8555: distances away for the the text that should appear at the beginning of the ! 8556: definition. ! 8557: ! 8558: If an empty argument is given (just type @key{RET}), the sexp in the ! 8559: buffer before or around point is used as the name of the tag to find. ! 8560: @xref{Lists}, for info on sexps. ! 8561: ! 8562: The argument to @code{find-tag} need not be the whole tag name; it can be ! 8563: a substring of a tag name. However, there can be many tag names containing ! 8564: the substring you specify. Since @code{find-tag} works by searching the ! 8565: text of the tag table, it finds the first tag in the table that the ! 8566: specified substring appears in. The way to find other tags that match the ! 8567: substring is to give @code{find-tag} a numeric argument, as in @kbd{C-u ! 8568: M-.}; this does not read a tag name, but continues searching the tag ! 8569: table's text for another tag containing the same substring last used. If ! 8570: you have a real @key{META} key, @kbd{M-0 M-.}@: is an easier alternative ! 8571: to @kbd{C-u M-.}. ! 8572: ! 8573: @kindex C-x 4 . ! 8574: @findex find-tag-other-window ! 8575: Like most commands that can switch buffers, @code{find-tag} has another ! 8576: similar command that displays the new buffer in another window. @kbd{C-x 4 ! 8577: .}@: invokes the function @code{find-tag-other-window}. (This key sequence ! 8578: ends with a period.) ! 8579: ! 8580: Emacs comes with a tag table file @file{TAGS}, in the directory ! 8581: containing Lisp libraries, which includes all the Lisp libraries and all ! 8582: the C sources of Emacs. By specifying this file with @code{visit-tags-table} ! 8583: and then using @kbd{M-.}@: you can quickly look at the source of any Emacs ! 8584: function. ! 8585: ! 8586: @node Tags Search, Tags Stepping, Find Tag, Tags ! 8587: @subsection Searching and Replacing with Tag Tables ! 8588: ! 8589: The commands in this section visit and search all the files listed in the ! 8590: selected tag table, one by one. For these commands, the tag table serves ! 8591: only to specify a sequence of files to search. A related command is ! 8592: @kbd{M-x grep} (@pxref{Compilation}). ! 8593: ! 8594: @table @kbd ! 8595: @item M-x tags-search ! 8596: Search for the specified regexp through the files in the selected tag ! 8597: table. ! 8598: @item M-x tags-query-replace ! 8599: Perform a @code{query-replace} on each file in the selected tag table. ! 8600: @item M-, ! 8601: Restart one of the commands above, from the current location of point ! 8602: (@code{tags-loop-continue}). ! 8603: @end table ! 8604: ! 8605: @findex tags-search ! 8606: @kbd{M-x tags-search} reads a regexp using the minibuffer, then visits ! 8607: the files of the selected tag table one by one, and searches through each ! 8608: one for that regexp. It displays the name of the file being searched so ! 8609: you can follow its progress. As soon as an occurrence is found, ! 8610: @code{tags-search} returns. ! 8611: ! 8612: @kindex M-, ! 8613: @findex tags-loop-continue ! 8614: Having found one match, you probably want to find all the rest. To find ! 8615: one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the ! 8616: @code{tags-search}. This searches the rest of the current buffer, followed ! 8617: by the remaining files of the tag table. ! 8618: ! 8619: @findex tags-query-replace ! 8620: @kbd{M-x tags-query-replace} performs a single @code{query-replace} ! 8621: through all the files in the tag table. It reads a string to search for ! 8622: and a string to replace with, just like ordinary @kbd{M-x query-replace}. ! 8623: It searches much like @kbd{M-x tags-search} but repeatedly, processing ! 8624: matches according to your input. @xref{Replace}, for more information on ! 8625: @code{query-replace}.@refill ! 8626: ! 8627: It is possible to get through all the files in the tag table with a ! 8628: single invocation of @kbd{M-x tags-query-replace}. But since any ! 8629: unrecognized character causes the command to exit, you may need to continue ! 8630: where you left off. @kbd{M-,} can be used for this. It resumes the last ! 8631: tags search or replace command that you did. ! 8632: ! 8633: It may have struck you that @code{tags-search} is a lot like @code{grep}. ! 8634: You can also run @code{grep} itself as an inferior of Emacs and have Emacs ! 8635: show you the matching lines one by one. This works mostly the same as ! 8636: running a compilation and having Emacs show you where the errors were. ! 8637: @xref{Compilation}. ! 8638: ! 8639: @node Tags Stepping, List Tags, Tags Search, Tags ! 8640: @subsection Stepping Through a Tag Table ! 8641: @findex next-file ! 8642: ! 8643: If you wish to process all the files in the selected tag table, but ! 8644: @kbd{M-x tags-search} and @kbd{M-x tags-query-replace} in particular are not what ! 8645: you want, you can use @kbd{M-x next-file}. ! 8646: ! 8647: @table @kbd ! 8648: @item C-u M-x next-file ! 8649: With a numeric argument, regardless of its value, visit the first ! 8650: file in the tag table, and prepare to advance sequentially by files. ! 8651: @item M-x next-file ! 8652: Visit the next file in the selected tag table. ! 8653: @end table ! 8654: ! 8655: @node List Tags,, Tags Stepping, Tags ! 8656: @subsection Tag Table Inquiries ! 8657: ! 8658: @table @kbd ! 8659: @item M-x list-tags ! 8660: Display a list of the tags defined in a specific program file. ! 8661: @item M-x tags-apropos ! 8662: Display a list of all tags matching a specified regexp. ! 8663: @end table ! 8664: ! 8665: @findex list-tags ! 8666: @kbd{M-x list-tags} reads the name of one of the files described by the ! 8667: selected tag table, and displays a list of all the tags defined in that ! 8668: file. The ``file name'' argument is really just a string to compare ! 8669: against the names recorded in the tag table; it is read as a string rather ! 8670: than as a file name. Therefore, completion and defaulting are not ! 8671: available, and you must enter the string the same way it appears in the tag ! 8672: table. Do not include a directory as part of the file name unless the file ! 8673: name recorded in the tag table includes a directory. ! 8674: ! 8675: @findex tags-apropos ! 8676: @kbd{M-x tags-apropos} is like @code{apropos} for tags. It reads a regexp, ! 8677: then finds all the tags in the selected tag table whose entries match that ! 8678: regexp, and displays the tag names found. ! 8679: ! 8680: @node Fortran,, Tags, Programs ! 8681: @section Fortran Mode ! 8682: @cindex Fortran mode ! 8683: ! 8684: Fortran mode provides special motion commands for Fortran statements and ! 8685: subprograms, and indentation commands that understand Fortran conventions ! 8686: of nesting, line numbers and continuation statements. ! 8687: ! 8688: Special commands for comments are provided because Fortran comments are ! 8689: unlike those of other languages. ! 8690: ! 8691: Built-in abbrevs optionally save typing when you insert Fortran keywords. ! 8692: ! 8693: @findex fortran-mode ! 8694: Use @kbd{M-x fortran-mode} to switch to this major mode. Doing so calls ! 8695: the value of @code{fortran-mode-hook} as a function of no arguments if ! 8696: that variable has a value that is not @code{nil}. ! 8697: ! 8698: @menu ! 8699: * Motion: Fortran Motion. Moving point by statements or subprograms. ! 8700: * Indent: Fortran Indent. Indentation commands for Fortran. ! 8701: * Comments: Fortran Comments. Inserting and aligning comments. ! 8702: * Columns: Fortran Columns. Measuring columns for valid Fortran. ! 8703: * Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords. ! 8704: @end menu ! 8705: ! 8706: Fortran mode was contributed by Michael Prange. ! 8707: ! 8708: @node Fortran Motion, Fortran Indent, Fortran, Fortran ! 8709: @subsection Motion Commands ! 8710: ! 8711: Fortran mode provides special commands to move by subprograms (functions ! 8712: and subroutines) and by statements. There is also a command to put the ! 8713: region around one subprogram, convenient for killing it or moving it. ! 8714: ! 8715: @kindex C-M-a (Fortran mode) ! 8716: @kindex C-M-e (Fortran mode) ! 8717: @kindex C-M-h (Fortran mode) ! 8718: @kindex C-c C-p (Fortran mode) ! 8719: @kindex C-c C-n (Fortran mode) ! 8720: @findex beginning-of-fortran-subprogram ! 8721: @findex end-of-fortran-subprogram ! 8722: @findex mark-fortran-subprogram ! 8723: @findex fortran-previous-statement ! 8724: @findex fortran-next-statement ! 8725: ! 8726: @table @kbd ! 8727: @item C-M-a ! 8728: Move to beginning of subprogram@* ! 8729: (@code{beginning-of-fortran-subprogram}). ! 8730: @item C-M-e ! 8731: Move to end of subprogram (@code{end-of-fortran-subprogram}). ! 8732: @item C-M-h ! 8733: Put point at beginning of subprogram and mark at end ! 8734: (@code{mark-fortran-subprogram}). ! 8735: @item C-c C-n ! 8736: Move to beginning of current or next statement ! 8737: (@code{fortran-next-statement}). ! 8738: @item C-c C-p ! 8739: Move to beginning of current or previous statement ! 8740: (@code{fortran-previous-statement}). ! 8741: @end table ! 8742: ! 8743: @node Fortran Indent, Fortran Comments, Fortran Motion, Fortran ! 8744: @subsection Fortran Indentation ! 8745: ! 8746: Special commands and features are needed for indenting Fortran code in ! 8747: order to make sure various syntactic entities (line numbers, comment line ! 8748: indicators and continuation line flags) appear in the columns that are ! 8749: required for standard Fortran. ! 8750: ! 8751: @menu ! 8752: * Commands: ForIndent Commands. Commands for indenting Fortran. ! 8753: * Numbers: ForIndent Num. How line numbers auto-indent. ! 8754: * Conv: ForIndent Conv. Conventions you must obey to avoid trouble. ! 8755: * Vars: ForIndent Vars. Variables controlling Fortran indent style. ! 8756: @end menu ! 8757: ! 8758: @node ForIndent Commands, ForIndent Num, Fortran Indent, Fortran Indent ! 8759: @subsubsection Fortran Indentation Commands ! 8760: ! 8761: @table @kbd ! 8762: @item @key{TAB} ! 8763: Indent the current line (@code{fortran-indent-line}). ! 8764: @item M-@key{LFD} ! 8765: Break the current line and set up a continuation line. ! 8766: @item C-M-q ! 8767: Indent all the lines of the subprogram point is in ! 8768: (@code{fortran-indent-subprogram}). ! 8769: @end table ! 8770: ! 8771: @findex fortran-indent-line ! 8772: @key{TAB} is redefined by Fortran mode to reindent the current line for ! 8773: Fortran (@code{fortran-indent-line}). Line numbers and continuation ! 8774: markers are indented to their required columns, and the body of the ! 8775: statement is independently indented based on its nesting in the program. ! 8776: ! 8777: @kindex C-M-q (Fortran mode) ! 8778: @findex fortran-indent-subprogram ! 8779: The key @kbd{C-M-q} is redefined as @code{fortran-indent-subprogram}, a ! 8780: command to reindent all the lines of the Fortran subprogram (function or ! 8781: subroutine) containing point. ! 8782: ! 8783: @kindex M-LFD (Fortran mode) ! 8784: @findex fortran-split-line ! 8785: The key @kbd{M-@key{LFD}} is redefined as @code{fortran-split-line}, a ! 8786: command to split a line in the appropriate fashion for Fortran. In a ! 8787: non-comment line, the second half becomes a continuation line and is ! 8788: indented accordingly. In a comment line, both halves become separate ! 8789: comment lines. ! 8790: ! 8791: @node ForIndent Num, ForIndent Conv, ForIndent Commands, Fortran Indent ! 8792: @subsubsection Line Numbers and Continuation ! 8793: ! 8794: If a number is the first non-whitespace in the line, it is assumed to be ! 8795: a line number and is moved to columns 0 through 4. (Columns are always ! 8796: counted from 0 in GNU Emacs.) If the text on the line starts with the ! 8797: conventional Fortran continuation marker @samp{$}, it is moved to column 5. ! 8798: If the text begins with any non whitespace character in column 5, it is ! 8799: assumed to be an unconventional continuation marker and remains in column ! 8800: 5. ! 8801: ! 8802: @vindex fortran-line-number-indent ! 8803: Line numbers of four digits or less are normally indented one space. ! 8804: This amount is controlled by the variable @code{fortran-line-number-indent} ! 8805: which is the maximum indentation a line number can have. Line numbers ! 8806: are indented to right-justify them to end in column 4 unless that would ! 8807: require more than this maximum indentation. The default value of the ! 8808: variable is 1. ! 8809: ! 8810: @vindex fortran-electric-line-number ! 8811: Simply inserting a line number is enough to indent it according to these ! 8812: rules. As each digit is inserted, the indentation is recomputed. To turn ! 8813: off this feature, set the variable @code{fortran-electric-line-number} to ! 8814: @code{nil}. Then inserting line numbers is like inserting anything else. ! 8815: ! 8816: @node ForIndent Conv, ForIndent Vars, ForIndent Num, Fortran Indent ! 8817: @subsubsection Syntactic Conventions ! 8818: ! 8819: Fortran mode assumes that you follow certain conventions that simplify ! 8820: the task of understanding a Fortran program well enough to indent it ! 8821: properly: ! 8822: ! 8823: @vindex fortran-continuation-char ! 8824: @itemize @bullet ! 8825: @item ! 8826: Two nested @samp{do} loops never share a @samp{continue} statement. ! 8827: ! 8828: @item ! 8829: The same character appears in column 5 of all continuation lines, and ! 8830: this character is the value of the variable @code{fortran-continuation-char}. ! 8831: By default, this character is @samp{$}. ! 8832: @end itemize ! 8833: ! 8834: @noindent ! 8835: If you fail to follow these conventions, the indentation commands may ! 8836: indent some lines unaesthetically. However, a correct Fortran program will ! 8837: retain its meaning when reindented even if the conventions are not ! 8838: followed. ! 8839: ! 8840: @node ForIndent Vars,, ForIndent Conv, Fortran Indent ! 8841: @subsubsection Variables for Fortran Indentation ! 8842: ! 8843: @vindex fortran-do-indent ! 8844: @vindex fortran-if-indent ! 8845: @vindex fortran-continuation-indent ! 8846: @vindex fortran-check-all-num-for-matching-do ! 8847: @vindex fortran-minimum-statement-indent ! 8848: Several additional variables control how Fortran indentation works. ! 8849: ! 8850: @table @code ! 8851: @item fortran-do-indent ! 8852: Extra indentation within each level of @samp{do} statement (default 3). ! 8853: ! 8854: @item fortran-if-indent ! 8855: Extra indentation within each level of @samp{if} statement (default 3). ! 8856: ! 8857: @item fortran-continuation-indent ! 8858: Extra indentation for bodies of continuation lines (default 5). ! 8859: ! 8860: @item fortran-check-all-num-for-matching-do ! 8861: If this is @code{nil}, indentation assumes that each @samp{do} ! 8862: statement ends on a @samp{continue} statement. Therefore, when ! 8863: computing indentation for a statement other than @samp{continue}, it ! 8864: can save time by not checking for a @samp{do} statement ending there. ! 8865: If this is non-@code{nil}, indenting any numbered statement must check ! 8866: for a @samp{do} that ends there. The default is @code{nil}. ! 8867: ! 8868: @item fortran-minimum-statement-indent ! 8869: Minimum indentation for fortran statements. For standard Fortran, ! 8870: this is 6. Statement bodies will never be indented less than this ! 8871: much. ! 8872: @end table ! 8873: ! 8874: @node Fortran Comments, Fortran Columns, Fortran Indent, Fortran ! 8875: @subsection Comments ! 8876: ! 8877: The usual Emacs comment commands assume that a comment can follow a line ! 8878: of code. In Fortran, the standard comment syntax requires an entire line ! 8879: to be just a comment. Therefore, Fortran mode replaces the standard Emacs ! 8880: comment commands and defines some new variables. ! 8881: ! 8882: Fortran mode can also handle a nonstandard comment syntax where comments ! 8883: start with @samp{!} and can follow other text. Because only some Fortran ! 8884: compilers accept this syntax, Fortran mode will not insert such comments ! 8885: unless you have said in advance to do so. To do this, set the variable ! 8886: @code{comment-start} to @samp{"!"} (@pxref{Variables}). ! 8887: ! 8888: @table @kbd ! 8889: @item M-; ! 8890: Align comment or insert new comment (@code{fortran-comment-indent}). ! 8891: ! 8892: @item C-x ; ! 8893: Applies to nonstandard @samp{!} comments only. ! 8894: ! 8895: @item C-c ; ! 8896: Turn all lines of the region into comments, or (with arg) ! 8897: turn them back into real code (@code{fortran-comment-region}). ! 8898: @end table ! 8899: ! 8900: @kbd{M-;} in Fortran mode is redefined as the command ! 8901: @code{fortran-comment-indent}. Like the usual @kbd{M-;} command, this ! 8902: recognizes any kind of existing comment and aligns its text appropriately; ! 8903: if there is no existing comment, a comment is inserted and aligned. But ! 8904: inserting and aligning comments are not the same in Fortran mode as in ! 8905: other modes. ! 8906: ! 8907: When a new comment must be inserted, if the current line is blank, a ! 8908: full-line comment is inserted. On a non-blank line, a nonstandard @samp{!} ! 8909: comment is inserted if you have said you want to use them. Otherwise a ! 8910: full-line comment is inserted on a new line before the current line. ! 8911: ! 8912: Nonstandard @samp{!} comments are aligned like comments in other ! 8913: languages, but full-line comments are different. In a standard full-line ! 8914: comment, the comment delimiter itself must always appear in column zero. ! 8915: What can be aligned is the text within the comment. You can choose from ! 8916: three styles of alignment by setting the variable ! 8917: @code{fortran-comment-indent-style} to one of these values: ! 8918: ! 8919: @vindex fortran-comment-indent-style ! 8920: @vindex fortran-comment-line-column ! 8921: @table @code ! 8922: @item fixed ! 8923: The text is aligned at a fixed column, which is the value of ! 8924: @code{fortran-comment-line-column}. This is the default. ! 8925: @item relative ! 8926: The text is aligned as if it were a line of code, but with an ! 8927: additional @code{fortran-comment-line-column} columns of indentation. ! 8928: @item nil ! 8929: Text in full-line columns is not moved automatically. ! 8930: @end table ! 8931: ! 8932: @vindex fortran-comment-indent-char ! 8933: In addition, you can specify the character to be used to indent within ! 8934: full-line comments by setting the variable @code{fortran-comment-indent-char} ! 8935: to the character you want to use. ! 8936: ! 8937: @vindex comment-line-start ! 8938: @vindex comment-line-start-skip ! 8939: Fortran mode introduces two variables @code{comment-line-start} and ! 8940: @code{comment-line-start-skip} which play for full-line comments the same ! 8941: roles played by @code{comment-start} and @code{comment-start-skip} for ! 8942: ordinary text-following comments. Normally these are set properly by ! 8943: Fortran mode so you do not need to change them. ! 8944: ! 8945: The normal Emacs comment command @kbd{C-x ;} has not been redefined. ! 8946: If you use @samp{!} comments, this command can be used with them. Otherwise ! 8947: it is useless in Fortran mode. ! 8948: ! 8949: @kindex C-c ; (Fortran mode) ! 8950: @findex fortran-comment-region ! 8951: @vindex fortran-comment-region ! 8952: The command @kbd{C-c ;} (@code{fortran-comment-region}) turns all the ! 8953: lines of the region into comments by inserting the string @samp{C$$$} at ! 8954: the front of each one. With a numeric arg, the region is turned back into ! 8955: live code by deleting @samp{C$$$} from the front of each line in it. The ! 8956: string used for these comments can be controlled by setting the variable ! 8957: @code{fortran-comment-region}. Note that here we have an example of a ! 8958: command and a variable with the same name; these two uses of the name never ! 8959: conflict because in Lisp and in Emacs it is always clear from the context ! 8960: which one is meant. ! 8961: ! 8962: @node Fortran Columns, Fortran Abbrev, Fortran Comments, Fortran ! 8963: @subsection Columns ! 8964: ! 8965: @table @kbd ! 8966: @item C-c C-r ! 8967: Displays a ``column ruler'' momentarily above the current line ! 8968: (@code{fortran-column-ruler}). ! 8969: @item C-c C-w ! 8970: Splits the current window horizontally so that it is 72 columns wide. ! 8971: This may help you avoid going over that limit (@code{fortran-window-create}). ! 8972: @end table ! 8973: ! 8974: @kindex C-c C-r (Fortran mode) ! 8975: @findex fortran-column-ruler ! 8976: @vindex fortran-column-ruler ! 8977: The command @kbd{C-c C-r} (@code{fortran-column-ruler}) shows a column ! 8978: ruler momentarily above the current line. The comment ruler is two lines ! 8979: of text that show you the locations of columns with special significance ! 8980: in Fortran programs. Square brackets show the limits of the columns for ! 8981: line numbers, and curly brackets show the limits of the columns for the ! 8982: statement body. Column numbers appear above them. ! 8983: ! 8984: Note that the column numbers count from zero, as always in GNU Emacs. As ! 8985: a result, the numbers may not be those you are familiar with; but the ! 8986: actual positions in the line are standard Fortran. ! 8987: ! 8988: The text used to display the column ruler is the value of the variable ! 8989: @code{fortran-comment-ruler}. By changing this variable, you can change ! 8990: the display. ! 8991: ! 8992: @kindex C-c C-w (Fortran mode) ! 8993: @findex fortran-window-create ! 8994: For even more help, use @kbd{C-c C-w} (@code{fortran-window-create}), a ! 8995: command which splits the current window horizontally, making a window 72 ! 8996: columns wide. By editing in this window you can immediately see when you ! 8997: make a line too wide to be correct Fortran. ! 8998: ! 8999: @node Fortran Abbrev,, Fortran Columns, Fortran ! 9000: @subsection Fortran Keyword Abbrevs ! 9001: ! 9002: Fortran mode provides many built-in abbrevs for common keywords and ! 9003: declarations. These are the same sort of abbrev that you can define ! 9004: yourself. To use them, you must turn on Abbrev mode. @pxref{Abbrevs}. ! 9005: ! 9006: The built-in abbrevs are unusual in one way: they all start with a ! 9007: semicolon. You cannot normally use semicolon in an abbrev, but Fortran ! 9008: mode makes this possible by changing the syntax of semicolon to ``word ! 9009: constituent''. ! 9010: ! 9011: For example, one built-in Fortran abbrev is @samp{;c} for ! 9012: @samp{continue}. If you insert @samp{;c} and then insert a punctuation ! 9013: character such as a space or a newline, the @samp{;c} will change ! 9014: automatically to @samp{continue}, provided Abbrev mode is enabled.@refill ! 9015: ! 9016: Type @samp{;?} or @samp{;C-h} to display a list of all the built-in ! 9017: Fortran abbrevs and what they stand for. ! 9018: ! 9019: @node Running, Abbrevs, Programs, Top ! 9020: @chapter Compiling and Testing Programs ! 9021: ! 9022: The previous chapter discusses the Emacs commands that are useful for ! 9023: making changes in programs. This chapter deals with commands that assist ! 9024: in the larger process of developing and maintaining programs. ! 9025: ! 9026: @menu ! 9027: * Compilation:: Compiling programs in languages other than Lisp ! 9028: (C, Pascal, etc.) ! 9029: * Modes: Lisp Modes. Various modes for editing Lisp programs, with ! 9030: different facilities for running the Lisp programs. ! 9031: * Libraries: Lisp Libraries. Creating Lisp programs to run in Emacs. ! 9032: * Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer. ! 9033: * Eval: Lisp Eval. Executing a single Lisp expression in Emacs. ! 9034: * Debug: Lisp Debug. Debugging Lisp programs running in Emacs. ! 9035: * External Lisp:: Communicating through Emacs with a separate Lisp. ! 9036: @end menu ! 9037: ! 9038: @node Compilation, Lisp Modes, Running, Running ! 9039: @section Running `make', or Compilers Generally ! 9040: @cindex inferior process ! 9041: @cindex make ! 9042: @cindex compilation errors ! 9043: @cindex error log ! 9044: ! 9045: Emacs can run compilers for noninteractive languages such as C and ! 9046: Fortran as inferior processes, feeding the error log into an Emacs buffer. ! 9047: It can also parse the error messages and visit the files in which errors ! 9048: are found, moving point right to the line where the error occurred. ! 9049: ! 9050: @table @kbd ! 9051: @item M-x compile ! 9052: Run a compiler asynchronously under Emacs, with error messages to ! 9053: @samp{*compilation*} buffer. ! 9054: @item M-x grep ! 9055: Run @code{grep} asynchronously under Emacs, with matching lines ! 9056: listed in the buffer named @samp{*compilation*}. ! 9057: @item M-x kill-compiler ! 9058: @itemx M-x kill-grep ! 9059: Kill the running compilation or @code{grep} subprocess. ! 9060: @item C-x ` ! 9061: Visit the locus of the next compiler error message or @code{grep} match. ! 9062: @end table ! 9063: ! 9064: @findex compile ! 9065: To run @code{make} or another compiler, do @kbd{M-x compile}. This command ! 9066: reads a shell command line using the minibuffer, and then executes the ! 9067: specified command line in an inferior shell with output going to the buffer ! 9068: named @samp{*compilation*}. The current buffer's default directory is used ! 9069: as the working directory for the execution of the command; normally, ! 9070: therefore, the makefile comes from this directory. ! 9071: ! 9072: @vindex compile-command ! 9073: When the shell command line is read, the minibuffer appears containing a ! 9074: default command line, which is the command you used the last time you did ! 9075: @kbd{M-x compile}. If you type just @key{RET}, the same command line is used ! 9076: again. The first @kbd{M-x compile} provides @code{make -k} as the default. ! 9077: The default is taken from the variable @code{compile-command}; if the ! 9078: appropriate compilation command for a file is something other than ! 9079: @code{make -k}, it can be useful to have the file specify a local value for ! 9080: @code{compile-command} (@pxref{File Variables}). ! 9081: ! 9082: Starting a compilation causes the buffer @samp{*compilation*} to be ! 9083: displayed in another window but not selected. Its mode line tells you ! 9084: whether compilation is finished, with the word @samp{run} or @samp{exit} inside ! 9085: the parentheses. You do not have to keep this buffer visible; compilation ! 9086: continues in any case. ! 9087: ! 9088: @findex kill-compilation ! 9089: To kill the compilation process, do @kbd{M-x kill-compilation}. You will ! 9090: see that the mode line of the @samp{*compilation*} buffer changes to say ! 9091: @samp{signal} instead of @samp{run}. Starting a new compilation also kills ! 9092: any running compilation, as only one can exist at any time. However, this ! 9093: requires confirmation before actually killing a compilation that is ! 9094: running.@refill ! 9095: ! 9096: @kindex C-x ` ! 9097: @findex next-error ! 9098: To parse the compiler error messages, type @kbd{C-x `} (@code{next-error}). The ! 9099: character following the @kbd{C-x} is the grave accent, not the single ! 9100: quote. This command displays the buffer @samp{*compilation*} in one window ! 9101: and the buffer in which the next error occurred in another window. Point ! 9102: in that buffer is moved to the line where the error was found. The ! 9103: corresponding error message is scrolled to the top of the window in which ! 9104: @samp{*compilation*} is displayed. ! 9105: ! 9106: The first time @kbd{C-x `} is used after the start of a compilation, it ! 9107: parses all the error messages, visits all the files that have error ! 9108: messages, and makes markers pointing at the lines that the error messages ! 9109: refer to. Then it moves to the first error message location. Subsequent ! 9110: uses of @kbd{C-x `} advance down the data set up by the first use. When ! 9111: the preparsed error messages are exhausted, the next @kbd{C-x `} checks for ! 9112: any more error messages that have come in; this is useful if you start ! 9113: editing the compiler errors while the compilation is still going on. If no ! 9114: more error messages have come in, @kbd{C-x `} reports an error. ! 9115: ! 9116: @kbd{C-u C-x `} discards the preparsed error message data and parses the ! 9117: @samp{*compilation*} buffer over again, then displaying the first error. ! 9118: This way, you can process the same set of errors again. ! 9119: ! 9120: Instead of running a compiler, you can run @code{grep} and see the lines ! 9121: on which matches were found. To do this, type @kbd{M-x grep} with an argument ! 9122: line that contains the same arguments you would give @code{grep} when running ! 9123: it normally: a @code{grep}-style regexp (usually in singlequotes to quote ! 9124: the shell's special characters) followed by filenames which may use wildcards. ! 9125: The output from @code{grep} goes in the @samp{*compilation*} buffer and the ! 9126: lines that matched can be found with @kbd{C-x `} as if they were compilation ! 9127: errors. ! 9128: ! 9129: Note: a shell is used to run the compile command, but the shell is told ! 9130: that it should be noninteractive. This means in particular that the shell ! 9131: starts up with no prompt. If you find your usual shell prompt making an ! 9132: unsightly appearance in the @samp{*compilation*} buffer, it means you have ! 9133: made a mistake in your shell's init file (@file{.cshrc} or @file{.shrc} or ! 9134: @dots{}) by setting the prompt unconditionally. The shell init file should ! 9135: set the prompt only if there already is a prompt. In @code{csh}, here is ! 9136: how to do it: ! 9137: ! 9138: @example ! 9139: if ($?prompt) set prompt = ... ! 9140: @end example ! 9141: ! 9142: @node Lisp Modes, Lisp Libraries, Compilation, Running ! 9143: @section Major Modes for Lisp ! 9144: ! 9145: Emacs has four different major modes for Lisp. They are the same in ! 9146: terms of editing commands, but differ in the commands for executing Lisp ! 9147: expressions. ! 9148: ! 9149: @table @asis ! 9150: @item Emacs-Lisp mode ! 9151: The mode for editing source files of programs to run in Emacs Lisp. ! 9152: This mode defines @kbd{C-M-x} to evaluate the current defun. ! 9153: @xref{Lisp Libraries}. ! 9154: @item Lisp Interaction mode ! 9155: The mode for an interactive session with Emacs Lisp. It defines ! 9156: @key{LFD} to evaluate the sexp before point and insert its value in the ! 9157: buffer. @xref{Lisp Interaction}. ! 9158: @item Lisp mode ! 9159: The mode for editing source files of programs that run in Lisps other ! 9160: than Emacs Lisp. This mode defines @kbd{C-M-x} to send the current defun ! 9161: to an inferior Lisp process. @xref{External Lisp}. ! 9162: @item Inferior Lisp mode ! 9163: The mode for an interactive session with an inferior Lisp process. ! 9164: This mode combines the special features of Lisp mode and Shell mode ! 9165: (@pxref{Shell Mode}). ! 9166: @item Scheme mode ! 9167: Like Lisp mode but for Scheme programs. ! 9168: @item Inferior Scheme mode ! 9169: The mode for an interactive session with an inferior Scheme process. ! 9170: @end table ! 9171: ! 9172: @node Lisp Libraries, Lisp Eval, Lisp Modes, Running ! 9173: @section Libraries of Lisp Code for Emacs ! 9174: @cindex libraries ! 9175: @cindex loading Lisp code ! 9176: ! 9177: Lisp code for Emacs editing commands is stored in files whose names ! 9178: conventionally end in @file{.el}. This ending tells Emacs to edit them in ! 9179: Emacs-Lisp mode (@pxref{Lisp Modes}). ! 9180: ! 9181: @menu ! 9182: * Loading:: Loading libraries of Lisp code into Emacs for use. ! 9183: * Compiling Libraries:: Compiling a library makes it load and run faster. ! 9184: * Mocklisp:: Converting Mocklisp to Lisp so GNU Emacs can run it. ! 9185: @end menu ! 9186: ! 9187: @node Loading, Compiling Libraries, Lisp Libraries, Lisp Libraries ! 9188: @subsection Loading Libraries ! 9189: ! 9190: @findex load-file ! 9191: To execute a file of Emacs Lisp, use @kbd{M-x load-file}. This command ! 9192: reads a file name using the minibuffer and then executes the contents of ! 9193: that file as Lisp code. It is not necessary to visit the file first; ! 9194: in any case, this command reads the file as found on disk, not text in ! 9195: an Emacs buffer. ! 9196: ! 9197: @findex load ! 9198: @findex load-library ! 9199: Once a file of Lisp code is installed in the Emacs Lisp library ! 9200: directories, users can load it using @kbd{M-x load-library}. Programs can ! 9201: load it by calling @code{load-library}, or with @code{load}, a more primitive ! 9202: function that is similar but accepts some additional arguments. ! 9203: ! 9204: @kbd{M-x load-library} differs from @kbd{M-x load-file} in that it ! 9205: searches a sequence of directories and tries three file names in each ! 9206: directory. The three names are, first, the specified name with @file{.elc} ! 9207: appended; second, with @file{.el} appended; third, the specified ! 9208: name alone. A @file{.elc} file would be the result of compiling the Lisp ! 9209: file into byte code; it is loaded if possible in preference to the Lisp ! 9210: file itself because the compiled file will load and run faster. ! 9211: ! 9212: Because the argument to @code{load-library} is usually not in itself ! 9213: a valid file name, file name completion is not available. Indeed, when ! 9214: using this command, you usually do not know exactly what file name ! 9215: will be used. ! 9216: ! 9217: @vindex load-path ! 9218: The sequence of directories searched by @kbd{M-x load-library} is ! 9219: specified by the variable @code{load-path}, a list of strings that are ! 9220: directory names. The default value of the list contains the directory where ! 9221: the Lisp code for Emacs itself is stored. If you have libraries of ! 9222: your own, put them in a single directory and add that directory ! 9223: to @code{load-path}. @code{nil} in this list stands for the current default ! 9224: directory, but it is probably not a good idea to put @code{nil} in the ! 9225: list. If you find yourself wishing that @code{nil} were in the list, ! 9226: most likely what you really want to do is use @kbd{M-x load-file} ! 9227: this once. ! 9228: ! 9229: @cindex autoload ! 9230: Often you do not have to give any command to load a library, because the ! 9231: commands defined in the library are set up to @dfn{autoload} that library. ! 9232: Running any of those commands causes @code{load} to be called to load the ! 9233: library; this replaces the autoload definitions with the real ones from the ! 9234: library. ! 9235: ! 9236: If autoloading a file does not finish, either because of an error or ! 9237: because of a @kbd{C-g} quit, all function definitions made by the file are ! 9238: undone automatically. So are any calls to @code{provide}. As a consequence, ! 9239: if you use one of the autoloadable commands again, the entire file will be ! 9240: loaded a second time. This prevents problems where the command is no ! 9241: longer autoloading but it works wrong because not all the file was loaded. ! 9242: Function definitions are undone only for autoloading; explicit calls to ! 9243: @code{load} do not undo anything if loading is not completed. ! 9244: ! 9245: @node Compiling Libraries, Mocklisp, Loading, Lisp Libraries ! 9246: @subsection Compiling Libraries ! 9247: ! 9248: @cindex byte code ! 9249: Emacs Lisp code can be compiled into byte-code which loads faster, ! 9250: takes up less space when loaded, and executes faster. ! 9251: ! 9252: @findex byte-compile-file ! 9253: The way to make a byte-code compiled file from an Emacs-Lisp source file ! 9254: is with @kbd{M-x byte-compile-file}. The default argument for this ! 9255: function is the file visited in the current buffer. It reads the specified ! 9256: file, compiles it into byte code, and writes an output file whose name is ! 9257: made by appending @file{c} to the input file name. Thus, the file ! 9258: @file{rmail.el} would be compiled into @file{rmail.elc}. ! 9259: ! 9260: @findex byte-recompile-directory ! 9261: To recompile the changed Lisp files in a directory, use @kbd{M-x ! 9262: byte-recompile-directory}. Specify just the directory name as an argument. ! 9263: Each @file{.el} file that has been byte-compiled before is byte-compiled ! 9264: again if it has changed since the previous compilation. A numeric argument ! 9265: to this command tells it to offer to compile each @file{.el} file that has ! 9266: not already been compiled. You must answer @kbd{y} or @kbd{n} to each ! 9267: offer. ! 9268: ! 9269: @findex batch-byte-compile ! 9270: Emacs can be invoked noninteractively from the shell to do byte compilation ! 9271: with the aid of the function @code{batch-byte-compile}. In this case, ! 9272: the files to be compiled are specified with command-line arguments. ! 9273: Use a shell command of the form ! 9274: ! 9275: @example ! 9276: emacs -batch -f batch-byte-compile @var{files}... ! 9277: @end example ! 9278: ! 9279: Directory names may also be given as arguments; ! 9280: @code{byte-recompile-directory} is invoked (in effect) on each such directory. ! 9281: @code{batch-byte-compile} uses all the remaining command-line arguments as ! 9282: file or directory names, then kills the Emacs process. ! 9283: ! 9284: @findex disassemble ! 9285: @kbd{M-x disassemble} explains the result of byte compilation. Its ! 9286: argument is a function name. It displays the byte-compiled code in a help ! 9287: window in symbolic form, one instruction per line. If the instruction ! 9288: refers to a variable or constant, that is shown too. ! 9289: ! 9290: @node Mocklisp,,Compiling Libraries,Lisp Libraries ! 9291: @subsection Converting Mocklisp to Lisp ! 9292: ! 9293: @cindex mocklisp ! 9294: @findex convert-mocklisp-buffer ! 9295: GNU Emacs can run Mocklisp files by converting them to Emacs Lisp first. ! 9296: To convert a Mocklisp file, visit it and then type @kbd{M-x ! 9297: convert-mocklisp-buffer}. Then save the resulting buffer of Lisp file in a ! 9298: file whose name ends in @file{.el} and use the new file as a Lisp library. ! 9299: ! 9300: It does not currently work to byte-compile converted Mocklisp code. ! 9301: This is because converted Mocklisp code uses some special Lisp features ! 9302: to deal with Mocklisp's incompatible ideas of how arguments are evaluated ! 9303: and which values signify ``true'' or ``false''. ! 9304: ! 9305: @node Lisp Eval, Lisp Debug, Lisp Libraries, Running ! 9306: @section Evaluating Emacs-Lisp Expressions ! 9307: @cindex Emacs-Lisp mode ! 9308: ! 9309: @findex emacs-lisp-mode ! 9310: Lisp programs intended to be run in Emacs should be edited in Emacs-Lisp ! 9311: mode; this will happen automatically for file names ending in @file{.el}. ! 9312: By contrast, Lisp mode itself is used for editing Lisp programs intended ! 9313: for other Lisp systems. Emacs-Lisp mode can be selected with the command ! 9314: @kbd{M-x emacs-lisp-mode}. ! 9315: ! 9316: For testing of Lisp programs to run in Emacs, it is useful to be able to ! 9317: evaluate part of the program as it is found in the Emacs buffer. For ! 9318: example, after changing the text of a Lisp function definition, evaluating ! 9319: the definition installs the change for future calls to the function. ! 9320: Evaluation of Lisp expressions is also useful in any kind of editing task ! 9321: for invoking noninteractive functions (functions that are not commands). ! 9322: ! 9323: @table @kbd ! 9324: @item M-@key{ESC} ! 9325: Read a Lisp expression in the minibuffer, evaluate it, and print the ! 9326: value in the minibuffer (@code{eval-expression}). ! 9327: @item C-x C-e ! 9328: Evaluate the Lisp expression before point, and print the value in the ! 9329: minibuffer (@code{eval-last-sexp}). ! 9330: @item C-M-x ! 9331: Evaluate the defun containing or after point, and print the value in ! 9332: the minibuffer (@code{eval-defun}). ! 9333: @item M-x eval-region ! 9334: Evaluate all the Lisp expressions in the region. ! 9335: @item M-x eval-current-buffer ! 9336: Evaluate all the Lisp expressions in the buffer. ! 9337: @end table ! 9338: ! 9339: @kindex M-ESC ! 9340: @findex eval-expression ! 9341: @kbd{M-@key{ESC}} (@code{eval-expression}) is the most basic command for evaluating ! 9342: a Lisp expression interactively. It reads the expression using the ! 9343: minibuffer, so you can execute any expression on a buffer regardless of ! 9344: what the buffer contains. When the expression is evaluated, the current ! 9345: buffer is once again the buffer that was current when @kbd{M-@key{ESC}} was ! 9346: typed. ! 9347: ! 9348: @kbd{M-@key{ESC}} can easily confuse users who do not understand it, ! 9349: especially on keyboards with autorepeat where it can result from holding ! 9350: down the @key{ESC} key for too long. Therefore, @code{eval-expression} is ! 9351: normally a disabled command. Attempting to use this command asks for ! 9352: confirmation and gives you the option of enabling it; once you enable the ! 9353: command, confirmation will no longer be required for it. ! 9354: @xref{Disabling}.@refill ! 9355: ! 9356: @kindex C-M-x ! 9357: @findex eval-defun ! 9358: In Emacs-Lisp mode, the key @kbd{C-M-x} is bound to the function @code{eval-defun}, ! 9359: which parses the defun containing or following point as a Lisp expression ! 9360: and evaluates it. The value is printed in the echo area. This command is ! 9361: convenient for installing in the Lisp environment changes that you have ! 9362: just made in the text of a function definition. ! 9363: ! 9364: @kindex C-x C-e ! 9365: @findex eval-last-sexp ! 9366: The command @kbd{C-x C-e} (@code{eval-last-sexp}) performs a similar job ! 9367: but is available in all major modes, not just Emacs-Lisp mode. It finds ! 9368: the sexp before point, reads it as a Lisp expression, evaluates it, and ! 9369: prints the value in the echo area. It is sometimes useful to type in an ! 9370: expression and then, with point still after it, type @kbd{C-x C-e}. ! 9371: ! 9372: If @kbd{C-M-x} or @kbd{C-x C-e} is given a numeric argument, it prints the value ! 9373: by insertion into the current buffer at point, rather than in the echo ! 9374: area. The argument value does not matter. ! 9375: ! 9376: @findex eval-region ! 9377: @findex eval-current-buffer ! 9378: The most general command for evaluating Lisp expressions from a buffer is ! 9379: @code{eval-region}. @kbd{M-x eval-region} parses the text of the region as one or ! 9380: more Lisp expressions, evaluating them one by one. @kbd{M-x eval-current-buffer} ! 9381: is similar but evaluates the entire buffer. This is a reasonable way to ! 9382: install the contents of a file of Lisp code that you are just ready to ! 9383: test. After finding and fixing a bug, use @kbd{C-M-x} on each function ! 9384: that you change, to keep the Lisp world in step with the source file. ! 9385: ! 9386: @node Lisp Debug, Lisp Interaction, Lisp Eval, Running ! 9387: @section The Emacs-Lisp Debugger ! 9388: @cindex debugger ! 9389: ! 9390: @vindex debug-on-error ! 9391: @vindex debug-on-quit ! 9392: GNU Emacs contains a debugger for Lisp programs executing inside it. ! 9393: This debugger is normally not used; many commands frequently get Lisp ! 9394: errors when invoked in inappropriate contexts (such as @kbd{C-f} at the end ! 9395: of the buffer) and it would be very unpleasant for that to enter a special ! 9396: debugging mode. When you want to make Lisp errors invoke the debugger, you ! 9397: must set the variable @code{debug-on-error} to non-@code{nil}. Quitting ! 9398: with @kbd{C-g} is not considered an error, and @code{debug-on-error} has no ! 9399: effect on the handling of @kbd{C-g}. However, if you set ! 9400: @code{debug-on-quit} non-@code{nil}, @kbd{C-g} will invoke the debugger. ! 9401: This can be useful for debugging an infinite loop; type @kbd{C-g} once the ! 9402: loop has had time to reach its steady state. @code{debug-on-quit} has no ! 9403: effect on errors.@refill ! 9404: ! 9405: @findex debug-on-entry ! 9406: @findex cancel-debug-on-entry ! 9407: @findex debug ! 9408: You can also cause the debugger to be entered when a specified function ! 9409: is called, or at a particular place in Lisp code. Use @kbd{M-x ! 9410: debug-on-entry} with argument @var{fun-name} to cause function ! 9411: @var{fun-name} to enter the debugger as soon as it is called. Use ! 9412: @kbd{M-x cancel-debug-on-entry} to make the function stop entering the ! 9413: debugger when called. (Redefining the function also does this.) To enter ! 9414: the debugger from some other place in Lisp code, you must insert the ! 9415: expression @code{(debug)} there and install the changed code with ! 9416: @kbd{C-M-x}. @xref{Lisp Eval}.@refill ! 9417: ! 9418: When the debugger is entered, it displays the previously selected buffer ! 9419: in one window and a buffer named @samp{*Backtrace*} in another window. The ! 9420: backtrace buffer contains one line for each level of Lisp function ! 9421: execution currently going on. At the beginning of this buffer is a message ! 9422: describing the reason that the debugger was invoked (such as, what error ! 9423: message if it was invoked due to an error). ! 9424: ! 9425: The backtrace buffer is read-only, and is in a special major mode, ! 9426: Backtrace mode, in which letters are defined as debugger commands. The ! 9427: usual Emacs editing commands are available; you can switch windows to ! 9428: examine the buffer that was being edited at the time of the error, and you ! 9429: can also switch buffers, visit files, and do any other sort of editing. ! 9430: However, the debugger is a recursive editing level (@pxref{Recursive Edit}) ! 9431: and it is wise to go back to the backtrace buffer and exit the debugger ! 9432: officially when you don't want to use it any more. Exiting the debugger ! 9433: kills the backtrace buffer. ! 9434: ! 9435: @cindex current stack frame ! 9436: The contents of the backtrace buffer show you the functions that are ! 9437: executing and the arguments that were given to them. It has the additional ! 9438: purpose of allowing you to specify a stack frame by moving point to the line ! 9439: describing that frame. The frame whose line point is on is considered the ! 9440: @dfn{current frame}. Some of the debugger commands operate on the current ! 9441: frame. Debugger commands are mainly used for stepping through code an ! 9442: expression at a time. Here is a list of them. ! 9443: ! 9444: @table @kbd ! 9445: @item c ! 9446: Exit the debugger and continue execution. In most cases, execution of ! 9447: the program continues as if the debugger had never been entered (aside ! 9448: from the effect of any variables or data structures you may have ! 9449: changed while inside the debugger). This includes entry to the ! 9450: debugger due to function entry or exit, explicit invocation, quitting ! 9451: or certain errors. Most errors cannot be continued; trying to ! 9452: continue one of them causes the same error to occur again. ! 9453: @item d ! 9454: Continue execution, but enter the debugger the next time a Lisp ! 9455: function is called. This allows you to step through the ! 9456: subexpressions of an expression, seeing what values the subexpressions ! 9457: compute and what else they do. ! 9458: ! 9459: The stack frame made for the function call which enters the debugger ! 9460: in this way will be flagged automatically for the debugger to be called ! 9461: when the frame is exited. You can use the @kbd{u} command to cancel ! 9462: this flag. ! 9463: @item b ! 9464: Set up to enter the debugger when the current frame is exited. Frames ! 9465: that will invoke the debugger on exit are flagged with stars. ! 9466: @item u ! 9467: Don't enter the debugger when the current frame is exited. This ! 9468: cancels a @kbd{b} command on that frame. ! 9469: @item e ! 9470: Read a Lisp expression in the minibuffer, evaluate it, and print the ! 9471: value in the echo area. This is the same as the command @kbd{M-@key{ESC}}, ! 9472: except that @kbd{e} is not normally disabled like @kbd{M-@key{ESC}}. ! 9473: @item q ! 9474: Terminate the program being debugged; return to top-level Emacs ! 9475: command execution. ! 9476: ! 9477: If the debugger was entered due to a @kbd{C-g} but you really want ! 9478: to quit, not to debug, use the @kbd{q} command. ! 9479: @item r ! 9480: Return a value from the debugger. The value is computed by reading an ! 9481: expression with the minibuffer and evaluating it. ! 9482: ! 9483: The value returned by the debugger makes a difference when the debugger ! 9484: was invoked due to exit from a Lisp call frame (as requested with @kbd{b}); ! 9485: then the value specified in the @kbd{r} command is used as the value of ! 9486: that frame. ! 9487: ! 9488: The debugger's return value also matters with many errors. For example, ! 9489: @code{wrong-type-argument} errors will use the debugger's return value ! 9490: instead of the invalid argument; @code{no-catch} errors will use the ! 9491: debugger value as a throw tag instead of the tag that was not found. ! 9492: If an error was signaled by calling the Lisp function @code{signal}, ! 9493: the debugger's return value is returned as the value of @code{signal}. ! 9494: @end table ! 9495: ! 9496: @node Lisp Interaction, External Lisp, Lisp Debug, Running ! 9497: @section Lisp Interaction Buffers ! 9498: ! 9499: The buffer @samp{*scratch*} which is selected when Emacs starts up is ! 9500: provided for evaluating Lisp expressions interactively inside Emacs. Both ! 9501: the expressions you evaluate and their output goes in the buffer. ! 9502: ! 9503: The @samp{*scratch*} buffer's major mode is Lisp Interaction mode, which ! 9504: is the same as Emacs-Lisp mode except for one command, @key{LFD}. In ! 9505: Emacs-Lisp mode, @key{LFD} is an indentation command, as usual. In Lisp ! 9506: Interaction mode, @key{LFD} is bound to @code{eval-print-last-sexp}. This ! 9507: function reads the Lisp expression before point, evaluates it, and inserts ! 9508: the value in printed representation before point. ! 9509: ! 9510: Thus, the way to use the @samp{*scratch*} buffer is to insert Lisp expressions ! 9511: at the end, ending each one with @key{LFD} so that it will be evaluated. ! 9512: The result is a complete typescript of the expressions you have evaluated ! 9513: and their values. ! 9514: ! 9515: @findex lisp-interaction-mode ! 9516: The rationale for this feature is that Emacs must have a buffer when it ! 9517: starts up, but that buffer is not useful for editing files since a new ! 9518: buffer is made for every file that you visit. The Lisp interpreter ! 9519: typescript is the most useful thing I can think of for the initial buffer ! 9520: to do. @kbd{M-x lisp-interaction-mode} will put any buffer in Lisp ! 9521: Interaction mode. ! 9522: ! 9523: @node External Lisp,, Lisp Interaction, Running ! 9524: @section Running an External Lisp ! 9525: ! 9526: Emacs has facilities for running programs in other Lisp systems. You can ! 9527: run a Lisp process as an inferior of Emacs, and pass expressions to it to ! 9528: be evaluated. You can also pass changed function definitions directly from ! 9529: the Emacs buffers in which you edit the Lisp programs to the inferior Lisp ! 9530: process. ! 9531: ! 9532: @findex run-lisp ! 9533: To run an inferior Lisp process, type @kbd{M-x run-lisp}. This runs the ! 9534: program named @code{lisp}, the same program you would run by typing ! 9535: @code{lisp} as a shell command, with both input and output going through an ! 9536: Emacs buffer named @samp{*lisp*}. That is to say, any ``terminal output'' ! 9537: from Lisp will go into the buffer, advancing point, and any ``terminal ! 9538: input'' for Lisp comes from text in the buffer. To give input to Lisp, go ! 9539: to the end of the buffer and type the input, terminated by @key{RET}. The ! 9540: @samp{*lisp*} buffer is in Inferior Lisp mode, a mode which has all the ! 9541: special characteristics of Lisp mode and Shell mode (@pxref{Shell Mode}). ! 9542: ! 9543: @findex lisp-mode ! 9544: For the source files of programs to run in external Lisps, use Lisp mode. ! 9545: This mode can be selected with @kbd{M-x lisp-mode}, and is used automatically ! 9546: for files whose names end in @file{.l} or @file{.lisp}, as most Lisp ! 9547: systems usually expect. ! 9548: ! 9549: @kindex C-M-x ! 9550: @findex lisp-send-defun ! 9551: When you edit a function in a Lisp program you are running, the easiest ! 9552: way to send the changed definition to the inferior Lisp process is the key ! 9553: @kbd{C-M-x}. In Lisp mode, this runs the function @code{lisp-send-defun}, ! 9554: which finds the defun around or following point and sends it as input to ! 9555: the Lisp process. (Emacs can send input to any inferior process regardless ! 9556: of what buffer is current.) ! 9557: ! 9558: Contrast the meanings of @kbd{C-M-x} in Lisp mode (for editing programs ! 9559: to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp ! 9560: programs to be run in Emacs): in both modes it has the effect of installing ! 9561: the function definition that point is in, but the way of doing so is ! 9562: different according to where the relevant Lisp environment is found. ! 9563: @xref{Lisp Modes}. ! 9564: ! 9565: @node Abbrevs, Picture, Running, Top ! 9566: @chapter Abbrevs ! 9567: @cindex abbrevs ! 9568: @cindex expansion (of abbrevs) ! 9569: ! 9570: An @dfn{abbrev} is a word which @dfn{expands}, if you insert it, into some ! 9571: different text. Abbrevs are defined by the user to expand in specific ! 9572: ways. For example, you might define @samp{foo} as an abbrev expanding to ! 9573: @samp{find outer otter}. With this abbrev defined, you would be able to ! 9574: get @samp{find outer otter } into the buffer by typing @kbd{f o o @key{SPC}}. ! 9575: ! 9576: @findex abbrev-mode ! 9577: @vindex abbrev-mode ! 9578: Abbrevs expand only when Abbrev mode (a minor mode) is enabled. ! 9579: Disabling Abbrev mode does not cause abbrev definitions to be forgotten, ! 9580: but they do not expand until Abbrev mode is enabled again. The command ! 9581: @kbd{M-x abbrev-mode} toggles Abbrev mode; with a numeric argument, it ! 9582: turns Abbrev mode on if the argument is positive, off otherwise. ! 9583: @xref{Minor Modes}. @code{abbrev-mode} is also a variable; Abbrev mode is ! 9584: on when the variable is non-@code{nil}. The variable @code{abbrev-mode} ! 9585: automatically becomes local to the current buffer when it is set. ! 9586: ! 9587: Abbrev definitions can be @dfn{mode-specific}---active only in one major ! 9588: mode. Abbrevs can also have @dfn{global} definitions that are active in ! 9589: all major modes. The same abbrev can have a global definition and various ! 9590: mode-specific definitions for different major modes. A mode specific ! 9591: definition for the current major mode overrides a global definition. ! 9592: ! 9593: Abbrevs can be defined interactively during the editing session. Lists ! 9594: of abbrev definitions can also be saved in files and reloaded in later ! 9595: sessions. Some users keep extensive lists of abbrevs that they load in ! 9596: every session. ! 9597: ! 9598: A second kind of abbreviation facility is called the @dfn{dynamic ! 9599: expansion}. Dynamic abbrev expansion happens only when you give an ! 9600: explicit command and the result of the expansion depends only on the ! 9601: current contents of the buffer. @xref{Dynamic Abbrevs}. ! 9602: ! 9603: @menu ! 9604: * Defining Abbrevs:: Defining an abbrev, so it will expand when typed. ! 9605: * Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion. ! 9606: * Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs. ! 9607: * Saving Abbrevs:: Saving the entire list of abbrevs for another session. ! 9608: * Dynamic Abbrevs:: Abbreviations for words already in the buffer. ! 9609: @end menu ! 9610: ! 9611: @node Defining Abbrevs, Expanding Abbrevs, Abbrevs, Abbrevs ! 9612: @section Defining Abbrevs ! 9613: ! 9614: @table @kbd ! 9615: @item C-x + ! 9616: Define an abbrev to expand into some text before point ! 9617: (@code{add-global-abbrev}). ! 9618: @item C-x C-a ! 9619: Similar, but define an abbrev available only in the current major mode ! 9620: (@code{add-mode-abbrev}). ! 9621: @item C-x - ! 9622: Define a word in the buffer as an abbrev (@code{inverse-add-global-abbrev}). ! 9623: @item C-x C-h ! 9624: Define a word in the buffer as a mode-specific abbrev ! 9625: (@code{inverse-add-mode-abbrev}). ! 9626: @item M-x kill-all-abbrevs ! 9627: After this command, there are no abbrev definitions in effect. ! 9628: @end table ! 9629: ! 9630: @kindex C-x + ! 9631: @findex add-global-abbrev ! 9632: The usual way to define an abbrev is to enter the text you want the ! 9633: abbrev to expand to, position point after it, and type @kbd{C-x +} ! 9634: (@code{add-global-abbrev}). This reads the abbrev itself using the ! 9635: minibuffer, and then defines it as an abbrev for one or more words before ! 9636: point. Use a numeric argument to say how many words before point should be ! 9637: taken as the expansion. For example, to define the abbrev @samp{foo} as ! 9638: mentioned above, insert the text @samp{find outer otter} and then type ! 9639: @kbd{C-u 3 C-x + f o o @key{RET}}. ! 9640: ! 9641: An argument of zero to @kbd{C-x +} means to use the contents of the ! 9642: region as the expansion of the abbrev being defined. ! 9643: ! 9644: @kindex C-x C-a ! 9645: @findex add-mode-abbrev ! 9646: The command @kbd{C-x C-a} (@code{add-mode-abbrev}) is similar, but ! 9647: defines a mode-specific abbrev. Mode specific abbrevs are active only in a ! 9648: particular major mode. @kbd{C-x C-a} defines an abbrev for the major mode ! 9649: in effect at the time @kbd{C-x C-a} is typed. The arguments work the same ! 9650: as for @kbd{C-x +}. ! 9651: ! 9652: @kindex C-x - ! 9653: @findex inverse-add-global-abbrev ! 9654: @kindex C-x C-h ! 9655: @findex inverse-add-mode-abbrev ! 9656: If the text of the abbrev you want is already in the buffer instead of ! 9657: the expansion, use command @kbd{C-x -} (@code{inverse-add-global-abbrev}) ! 9658: instead of @kbd{C-x +}, or use @kbd{C-x C-h} ! 9659: (@code{inverse-add-mode-abbrev}) instead of @kbd{C-x C-a}. These commands ! 9660: are called ``inverse'' because they invert the meaning of the argument ! 9661: found in the buffer and the argument read using the minibuffer.@refill ! 9662: ! 9663: To change the definition of an abbrev, just add the new definition. You ! 9664: will be asked to confirm if the abbrev has a prior definition. To remove ! 9665: an abbrev definition, give a negative argument to @kbd{C-x +} or @kbd{C-x ! 9666: C-a}. You must choose the command to specify whether to kill a global ! 9667: definition or a mode-specific definition for the current mode, since those ! 9668: two definitions are independent for one abbrev. ! 9669: ! 9670: @findex kill-all-abbrevs ! 9671: @kbd{M-x kill-all-abbrevs} removes all the abbrev definitions there are. ! 9672: ! 9673: @node Expanding Abbrevs, Editing Abbrevs, Defining Abbrevs, Abbrevs ! 9674: @section Controlling Abbrev Expansion ! 9675: ! 9676: An abbrev expands whenever it is present in the buffer just before point ! 9677: and a self-inserting punctuation character (@key{SPC}, comma, etc.@:) is ! 9678: typed. Most often the way an abbrev is used is to insert the abbrev ! 9679: followed by punctuation. ! 9680: ! 9681: @vindex abbrev-all-caps ! 9682: Abbrev expansion preserves case; thus, @samp{foo} expands into @samp{find ! 9683: outer otter}; @samp{Foo} into @samp{Find outer otter}, and @samp{FOO} into ! 9684: @samp{FIND OUTER OTTER} or @samp{Find Outer Otter} according to the ! 9685: variable @code{abbrev-all-caps} (a non-@code{nil} value chooses the first ! 9686: of the two expansions).@refill ! 9687: ! 9688: These two commands are used to control abbrev expansion: ! 9689: ! 9690: @table @kbd ! 9691: @item M-' ! 9692: Separate a prefix from a following abbrev to be expanded ! 9693: (@code{abbrev-prefix-mark}). ! 9694: @item C-x ' ! 9695: @findex expand-abbrev ! 9696: Expand the abbrev before point (@code{expand-abbrev}). ! 9697: This is effective even when Abbrev mode is not enabled. ! 9698: @item M-x unexpand-abbrev ! 9699: Undo last abbrev expansion. ! 9700: @item M-x expand-region-abbrevs ! 9701: Expand some or all abbrevs found in the region. ! 9702: @end table ! 9703: ! 9704: @kindex M-' ! 9705: @findex abbrev-prefix-mark ! 9706: You may wish to expand an abbrev with a prefix attached; for example, if ! 9707: @samp{cnst} expands into @samp{construction}, you might want to use it to ! 9708: enter @samp{reconstruction}. It does not work to type @kbd{recnst}, ! 9709: because that is not necessarily a defined abbrev. What does work is to use ! 9710: the command @kbd{M-'} (@code{abbrev-prefix-mark}) in between the prefix ! 9711: @samp{re} and the abbrev @samp{cnst}. First, insert @samp{re}. Then type ! 9712: @kbd{M-'}; this inserts a minus sign in the buffer to indicate that it has ! 9713: done its work. Then insert the abbrev @samp{cnst}; the buffer now contains ! 9714: @samp{re-cnst}. Now insert a punctuation character to expand the abbrev ! 9715: @samp{cnst} into @samp{construction}. The minus sign is deleted at this ! 9716: point, because @kbd{M-'} left word for this to be done. The resulting text ! 9717: is the desired @samp{reconstruction}.@refill ! 9718: ! 9719: If you actually want the text of the abbrev in the buffer, rather than ! 9720: its expansion, you can accomplish this by inserting the following ! 9721: punctuation with @kbd{C-q}. Thus, @kbd{foo C-q -} leaves @samp{foo-} in the ! 9722: buffer. ! 9723: ! 9724: @findex unexpand-abbrev ! 9725: If you expand an abbrev by mistake, you can undo the expansion (replace ! 9726: the expansion by the original abbrev text) with @kbd{M-x unexpand-abbrev}. ! 9727: @kbd{C-_} (@code{undo}) can also be used to undo the expansion; but first ! 9728: it will undo the insertion of the following punctuation character! ! 9729: ! 9730: @findex expand-region-abbrevs ! 9731: @kbd{M-x expand-region-abbrevs} searches through the region for defined ! 9732: abbrevs, and for each one found offers to replace it with its expansion. ! 9733: This command is useful if you have typed in text using abbrevs but forgot ! 9734: to turn on Abbrev mode first. It may also be useful together with a ! 9735: special set of abbrev definitions for making several global replacements at ! 9736: once. This command is effective even if Abbrev mode is not enabled. ! 9737: ! 9738: @node Editing Abbrevs, Saving Abbrevs, Expanding Abbrevs, Abbrevs ! 9739: @section Examining and Editing Abbrevs ! 9740: ! 9741: @table @kbd ! 9742: @item M-x list-abbrevs ! 9743: Print a list of all abbrev definitions. ! 9744: @item M-x edit-abbrevs ! 9745: Edit a list of abbrevs; you can add, alter or remove definitions. ! 9746: @end table ! 9747: ! 9748: @findex list-abbrevs ! 9749: The output from @kbd{M-x list-abbrevs} looks like this: ! 9750: ! 9751: @example ! 9752: (lisp-mode-abbrev-table) ! 9753: "dk" 0 "define-key" ! 9754: (global-abbrev-table) ! 9755: "dfn" 0 "definition" ! 9756: @end example ! 9757: ! 9758: @noindent ! 9759: (Some blank lines of no semantic significance, and some other abbrev ! 9760: tables, have been omitted.) ! 9761: ! 9762: A line containing a name in parentheses is the header for abbrevs in a ! 9763: particular abbrev table; @code{global-abbrev-table} contains all the global ! 9764: abbrevs, and the other abbrev tables that are named after major modes ! 9765: contain the mode-specific abbrevs. ! 9766: ! 9767: Within each abbrev table, each nonblank line defines one abbrev. The ! 9768: word at the beginning is the abbrev. The number that appears is the number ! 9769: of times the abbrev has been expanded. Emacs keeps track of this to help ! 9770: you see which abbrevs you actually use, in case you decide to eliminate ! 9771: those that you don't use often. The string at the end of the line is the ! 9772: expansion. ! 9773: ! 9774: @findex edit-abbrevs ! 9775: @kindex C-c C-c (Edit Abbrevs) ! 9776: @findex edit-abbrevs-redefine ! 9777: @kbd{M-x edit-abbrevs} allows you to add, change or kill abbrev ! 9778: definitions by editing a list of them in an Emacs buffer. The list has the ! 9779: same format described above. The buffer of abbrevs is called @samp{*Abbrevs*}, ! 9780: and is in Edit-Abbrevs mode. This mode redefines the key @kbd{C-c C-c} to ! 9781: install the abbrev definitions as specified in the buffer. The command ! 9782: that does this is @code{edit-abbrevs-redefine}. Any abbrevs not described ! 9783: in the buffer are eliminated when this is done. ! 9784: ! 9785: @code{edit-abbrevs} is actually the same as @code{list-abbrevs} except ! 9786: that it selects the buffer @samp{*Abbrevs*} whereas @code{list-abbrevs} ! 9787: merely displays it in another window. ! 9788: ! 9789: @node Saving Abbrevs, Dynamic Abbrevs, Editing Abbrevs, Abbrevs ! 9790: @section Saving Abbrevs ! 9791: ! 9792: These commands allow you to keep abbrev definitions between editing ! 9793: sessions. ! 9794: ! 9795: @table @kbd ! 9796: @item M-x write-abbrev-file ! 9797: Write a file describing all defined abbrevs. ! 9798: @item M-x read-abbrev-file ! 9799: Read such a file and define abbrevs as specified there. ! 9800: @item M-x quietly-read-abbrev-file ! 9801: Similar but do not display a message about what is going on. ! 9802: @item M-x define-abbrevs ! 9803: Define abbrevs from buffer. ! 9804: @item M-x insert-abbrevs ! 9805: Insert all abbrevs and their expansions into the buffer. ! 9806: @end table ! 9807: ! 9808: @findex write-abbrev-file ! 9809: @kbd{M-x write-abbrev-file} reads a file name using the minibuffer and ! 9810: writes a description of all current abbrev definitions into that file. The ! 9811: text stored in the file looks like the output of @kbd{M-x list-abbrevs}. ! 9812: This is used to save abbrev definitions for use in a later session. ! 9813: ! 9814: @findex read-abbrev-file ! 9815: @findex quietly-read-abbrev-file ! 9816: @vindex abbrev-file-name ! 9817: @kbd{M-x read-abbrev-file} reads a file name using the minibuffer and ! 9818: reads the file, defining abbrevs according to the contents of the file. ! 9819: @kbd{M-x quietly-read-abbrev-file} is the same except that it does not ! 9820: display a message in the echo area saying that it is doing its work; it ! 9821: is actually useful primarily in the @file{.emacs} file. If an empty ! 9822: argument is given to either of these functions, the file name used is the ! 9823: value of the variable @code{abbrev-file-name}, which is by default ! 9824: @code{"~/.abbrev_defs"}. ! 9825: ! 9826: @vindex save-abbrevs ! 9827: Emacs will offer to save abbrevs automatically if you have changed any of ! 9828: them, whenever it offers to save all files (for @kbd{C-x s} or @kbd{C-x ! 9829: C-c}). This feature can be inhibited by setting the variable ! 9830: @code{save-abbrevs} to @code{nil}. ! 9831: ! 9832: @findex insert-abbrevs ! 9833: @findex define-abbrevs ! 9834: The commands @kbd{M-x insert-abbrevs} and @kbd{M-x define-abbrevs} are ! 9835: similar to the previous commands but work on text in an Emacs buffer. ! 9836: @kbd{M-x insert-abbrevs} inserts text into the current buffer before point, ! 9837: describing all current abbrev definitions; @kbd{M-x define-abbrevs} parses ! 9838: the entire current buffer and defines abbrevs accordingly.@refill ! 9839: ! 9840: @node Dynamic Abbrevs,, Saving Abbrevs, Abbrevs ! 9841: @section Dynamic Abbrev Expansion ! 9842: ! 9843: The abbrev facility described above operates automatically as you insert ! 9844: text, but all abbrevs must be defined explicitly. By contrast, ! 9845: @dfn{dynamic abbrevs} allow the meanings of abbrevs to be determined ! 9846: automatically from the contents of the buffer, but dynamic abbrev expansion ! 9847: happens only when you request it explicitly. ! 9848: ! 9849: @kindex M-/ ! 9850: @findex dabbrev-expand ! 9851: @table @kbd ! 9852: @item M-/ ! 9853: Expand the word in the buffer before point as a @dfn{dynamic abbrev}, ! 9854: by searching in the buffer for words starting with that abbreviation ! 9855: (@code{dabbrev-expand}). ! 9856: @end table ! 9857: ! 9858: For example, if the buffer contains @samp{does this follow } and you type ! 9859: @kbd{f o M-/}, the effect is to insert @samp{follow} because that is the ! 9860: last word in the buffer that starts with @samp{fo}. A numeric argument to ! 9861: @kbd{M-/} says to take the second, third, etc.@: distinct expansion found ! 9862: looking backward from point. Repeating @kbd{M-/} searches for an ! 9863: alternative expansion by looking farther back. After the entire buffer ! 9864: before point has been considered, the buffer after point is searched. ! 9865: ! 9866: Dynamic abbrev expansion is completely independent of Abbrev mode; the ! 9867: expansion of a word with @kbd{M-/} is completely independent of whether it ! 9868: has a definition as an ordinary abbrev. ! 9869: ! 9870: @node Picture, Sending Mail, Abbrevs, Top ! 9871: @chapter Editing Pictures ! 9872: @cindex pictures ! 9873: @findex edit-picture ! 9874: ! 9875: If you want to create a picture made out of text characters (for example, ! 9876: a picture of the division of a register into fields, as a comment in a ! 9877: program), use the command @code{edit-picture} to enter Picture mode. ! 9878: ! 9879: In Picture mode, editing is based on the @dfn{quarter-plane} model of ! 9880: text, according to which the text characters lie studded on an area that ! 9881: stretches infinitely far to the right and downward. The concept of the end ! 9882: of a line does not exist in this model; the most you can say is where the ! 9883: last nonblank character on the line is found. ! 9884: ! 9885: Of course, Emacs really always considers text as a sequence of ! 9886: characters, and lines really do have ends. But in Picture mode most ! 9887: frequently-used keys are rebound to commands that simulate the ! 9888: quarter-plane model of text. They do this by inserting spaces or by ! 9889: converting tabs to spaces. ! 9890: ! 9891: Most of the basic editing commands of Emacs are redefined by Picture mode ! 9892: to do essentially the same thing but in a quarter-plane way. In addition, ! 9893: Picture mode defines various keys starting with the @kbd{C-c} prefix to ! 9894: run special picture editing commands. ! 9895: ! 9896: One of these keys, @kbd{C-c C-c}, is pretty important. Often a picture ! 9897: is part of a larger file that is usually edited in some other major mode. ! 9898: @kbd{M-x edit-picture} records the name of the previous major mode, and ! 9899: then you can use the @kbd{C-c C-c} command (@code{picture-mode-exit}) to ! 9900: restore that mode. @kbd{C-c C-c} also deletes spaces from the ends of ! 9901: lines, unless given a numeric argument. ! 9902: ! 9903: The commands used in Picture mode all work in other modes (provided the ! 9904: @file{picture} library is loaded), but are not bound to keys except in ! 9905: Picture mode. Note that the descriptions below talk of moving ``one ! 9906: column'' and so on, but all the picture mode commands handle numeric ! 9907: arguments as their normal equivalents do. ! 9908: ! 9909: @vindex picture-mode-hook ! 9910: Turning on Picture mode calls the value of the variable @code{picture-mode-hook} ! 9911: as a function, with no arguments, if that value exists and is non-@code{nil}. ! 9912: ! 9913: @menu ! 9914: * Basic Picture:: Basic concepts and simple commands of Picture Mode. ! 9915: * Insert in Picture:: Controlling direction of cursor motion ! 9916: after "self-inserting" characters. ! 9917: * Tabs in Picture:: Various features for tab stops and indentation. ! 9918: * Rectangles in Picture:: Clearing and superimposing rectangles. ! 9919: @end menu ! 9920: ! 9921: @node Basic Picture, Insert in Picture, Picture, Picture ! 9922: @section Basic Editing in Picture Mode ! 9923: ! 9924: @findex picture-forward-column ! 9925: @findex picture-backward-column ! 9926: @findex picture-move-down ! 9927: @findex picture-move-up ! 9928: Most keys do the same thing in Picture mode that they usually do, but do ! 9929: it in a quarter-plane style. For example, @kbd{C-f} is rebound to run ! 9930: @code{picture-forward-column}, which is defined to move point one column to ! 9931: the right, by inserting a space if necessary, so that the actual end of the ! 9932: line makes no difference. @kbd{C-b} is rebound to run ! 9933: @code{picture-backward-column}, which always moves point left one column, ! 9934: converting a tab to multiple spaces if necessary. @kbd{C-n} and @kbd{C-p} ! 9935: are rebound to run @code{picture-move-down} and @code{picture-move-up}, ! 9936: which can either insert spaces or convert tabs as necessary to make sure ! 9937: that point stays in exactly the same column. @kbd{C-e} runs ! 9938: @code{picture-end-of-line}, which moves to after the last nonblank ! 9939: character on the line. There is no need to change @kbd{C-a}, as the choice ! 9940: of screen model does not affect beginnings of lines.@refill ! 9941: ! 9942: @findex picture-newline ! 9943: Insertion of text is adapted to the quarter-plane screen model through ! 9944: the use of Overwrite mode (@pxref{Minor Modes}). Self-inserting characters ! 9945: replace existing text, column by column, rather than pushing existing text ! 9946: to the right. @key{RET} runs @code{picture-newline}, which just moves to ! 9947: the beginning of the following line so that new text will replace that ! 9948: line. ! 9949: ! 9950: @findex picture-backward-clear-column ! 9951: @findex picture-clear-column ! 9952: @findex picture-clear-line ! 9953: Deletion and killing of text are replaced with erasure. @key{DEL} ! 9954: (@code{picture-backward-clear-column}) replaces the preceding character ! 9955: with a space rather than removing it. @kbd{C-d} ! 9956: (@code{picture-clear-column}) does the same thing in a forward direction. ! 9957: @kbd{C-k} (@code{picture-clear-line}) really kills the contents of lines, ! 9958: but does not ever remove the newlines from the buffer.@refill ! 9959: ! 9960: @findex picture-open-line ! 9961: To do actual insertion, you must use special commands. @kbd{C-o} ! 9962: (@code{picture-open-line}) still creates a blank line, but does so after ! 9963: the current line; it never splits a line. @kbd{C-M-o}, @code{split-line}, ! 9964: makes sense in Picture mode, so it is not changed. @key{LFD} ! 9965: (@code{picture-duplicate-line}) inserts below the current line another line ! 9966: with the same contents.@refill ! 9967: ! 9968: @kindex C-c C-d (Picture mode) ! 9969: @findex delete-char ! 9970: Real deletion can be done with @kbd{C-w}, or with @kbd{C-c C-d} (which is ! 9971: defined as @code{delete-char}, as @kbd{C-d} is in other modes), or with one ! 9972: of the picture rectangle commands (@pxref{Rectangles in Picture}). ! 9973: ! 9974: @node Insert in Picture, Tabs in Picture, Basic Picture, Picture ! 9975: @section Controlling Motion after Insert ! 9976: ! 9977: @findex picture-movement-up ! 9978: @findex picture-movement-down ! 9979: @findex picture-movement-left ! 9980: @findex picture-movement-right ! 9981: @findex picture-movement-nw ! 9982: @findex picture-movement-ne ! 9983: @findex picture-movement-sw ! 9984: @findex picture-movement-se ! 9985: @kindex C-c < (Picture mode) ! 9986: @kindex C-c > (Picture mode) ! 9987: @kindex C-c ^ (Picture mode) ! 9988: @kindex C-c . (Picture mode) ! 9989: @kindex C-c ` (Picture mode) ! 9990: @kindex C-c ' (Picture mode) ! 9991: @kindex C-c / (Picture mode) ! 9992: @kindex C-c \ (Picture mode) ! 9993: Since ``self-inserting'' characters in Picture mode just overwrite and ! 9994: move point, there is no essential restriction on how point should be moved. ! 9995: Normally point moves right, but you can specify any of the eight orthogonal ! 9996: or diagonal directions for motion after a ``self-inserting'' character. ! 9997: This is useful for drawing lines in the buffer. ! 9998: ! 9999: @table @kbd ! 10000: @item C-c < ! 10001: Move left after insertion (@code{picture-movement-left}). ! 10002: @item C-c > ! 10003: Move right after insertion (@code{picture-movement-right}). ! 10004: @item C-c ^ ! 10005: Move up after insertion (@code{picture-movement-up}). ! 10006: @item C-c . ! 10007: Move down after insertion (@code{picture-movement-down}). ! 10008: @item C-c ` ! 10009: Move up and left (``northwest'') after insertion @*(@code{picture-movement-nw}). ! 10010: @item C-c ' ! 10011: Move up and right (``northeast'') after insertion @* ! 10012: (@code{picture-movement-ne}). ! 10013: @item C-c / ! 10014: Move down and left (``southwest'') after insertion ! 10015: @*(@code{picture-movement-sw}). ! 10016: @item C-c \ ! 10017: Move down and right (``southeast'') after insertion ! 10018: @*(@code{picture-movement-se}). ! 10019: @end table ! 10020: ! 10021: @kindex C-c C-f (Picture mode) ! 10022: @kindex C-c C-b (Picture mode) ! 10023: @findex picture-motion ! 10024: @findex picture-motion-reverse ! 10025: Two motion commands move based on the current Picture insertion ! 10026: direction. The command @kbd{C-c C-f} (@code{picture-motion}) moves in the ! 10027: same direction as motion after ``insertion'' currently does, while @kbd{C-c ! 10028: C-b} (@code{picture-motion-reverse}) moves in the opposite direction. ! 10029: ! 10030: @node Tabs in Picture, Rectangles in Picture, Insert in Picture, Picture ! 10031: @section Picture Mode Tabs ! 10032: ! 10033: @kindex M-TAB ! 10034: @findex picture-tab-search ! 10035: @vindex picture-tab-chars ! 10036: Two kinds of tab-like action are provided in Picture mode. ! 10037: Context-based tabbing is done with @kbd{M-@key{TAB}} ! 10038: (@code{picture-tab-search}). With no argument, it moves to a point ! 10039: underneath the next ``interesting'' character that follows whitespace in ! 10040: the previous nonblank line. ``Next'' here means ``appearing at a ! 10041: horizontal position greater than the one point starts out at''. With an ! 10042: argument, as in @kbd{C-u M-@key{TAB}}, this command moves to the next such ! 10043: interesting character in the current line. @kbd{M-@key{TAB}} does not ! 10044: change the text; it only moves point. ``Interesting'' characters are ! 10045: defined by the variable @code{picture-tab-chars}, which contains a string ! 10046: whose characters are all considered interesting. Its default value is ! 10047: @code{"!-~"}.@refill ! 10048: ! 10049: @findex picture-tab ! 10050: @key{TAB} itself runs @code{picture-tab}, which operates based on the ! 10051: current tab stop settings; it is the Picture mode equivalent of ! 10052: @code{tab-to-tab-stop}. Normally it just moves point, but with a numeric ! 10053: argument it clears the text that it moves over. ! 10054: ! 10055: @kindex C-c TAB (Picture mode) ! 10056: @findex picture-set-tab-stops ! 10057: The context-based and tab-stop-based forms of tabbing are brought ! 10058: together by the command @kbd{C-c @key{TAB}}, @code{picture-set-tab-stops}. ! 10059: This command sets the tab stops to the positions which @kbd{M-@key{TAB}} ! 10060: would consider significant in the current line. The use of this command, ! 10061: together with @key{TAB}, can get the effect of context-based tabbing. But ! 10062: @kbd{M-@key{TAB}} is more convenient in the cases where it is sufficient. ! 10063: ! 10064: @node Rectangles in Picture,, Tabs in Picture, Picture ! 10065: @section Picture Mode Rectangle Commands ! 10066: @cindex rectangle ! 10067: ! 10068: Picture mode defines commands for working on rectangular pieces of the ! 10069: text in ways that fit with the quarter-plane model. The standard rectangle ! 10070: commands may also be useful (@pxref{Rectangles}). ! 10071: ! 10072: @table @kbd ! 10073: @item C-c C-k ! 10074: Clear out the region-rectangle (@code{picture-clear-rectangle}). With ! 10075: argument, kill it. ! 10076: @item C-c C-w @var{r} ! 10077: Similar but save rectangle contents in register @var{r} first ! 10078: (@code{picture-clear-rectangle-to-register}). ! 10079: @item C-c C-y ! 10080: Copy last killed rectangle into the buffer by overwriting, with upper ! 10081: left corner at point (@code{picture-yank-rectangle}). With argument, ! 10082: insert instead. ! 10083: @item C-c C-x @var{r} ! 10084: Similar, but use the rectangle in register @var{r}@* ! 10085: (@code{picture-yank-rectangle-from-register}). ! 10086: @end table ! 10087: ! 10088: @kindex C-c C-k (Picture mode) ! 10089: @kindex C-c C-w (Picture mode) ! 10090: @findex picture-clear-rectangle ! 10091: @findex picture-clear-rectangle-to-register ! 10092: The picture rectangle commands @kbd{C-c C-k} ! 10093: (@code{picture-clear-rectangle}) and @kbd{C-c C-w} ! 10094: (@code{picture-clear-rectangle-to-register}) differ from the standard ! 10095: rectangle commands in that they normally clear the rectangle instead of ! 10096: deleting it; this is analogous with the way @kbd{C-d} is changed in Picture ! 10097: mode.@refill ! 10098: ! 10099: However, deletion of rectangles can be useful in Picture mode, so these ! 10100: commands delete the rectangle if given a numeric argument. ! 10101: ! 10102: @kindex C-c C-y (Picture mode) ! 10103: @kindex C-c C-x (Picture mode) ! 10104: @findex picture-yank-rectangle ! 10105: @findex picture-yank-rectangle-from-register ! 10106: The Picture mode commands for yanking rectangles differ from the standard ! 10107: ones in overwriting instead of inserting. This is the same way that ! 10108: Picture mode insertion of other text is different from other modes. ! 10109: @kbd{C-c C-y} (@code{picture-yank-rectangle}) inserts (by overwriting) the ! 10110: rectangle that was most recently killed, while @kbd{C-c C-x} ! 10111: (@code{picture-yank-rectangle-from-register}) does likewise for the ! 10112: rectangle found in a specified register. ! 10113: ! 10114: @node Sending Mail, Rmail, Picture, Top ! 10115: @chapter Sending Mail ! 10116: @cindex mail ! 10117: @cindex message ! 10118: ! 10119: To send a message in Emacs, you start by typing a command (@kbd{C-x m}) ! 10120: to select and initialize the @samp{*mail*} buffer. Then you edit the text ! 10121: and headers of the message in this buffer, and type another command ! 10122: (@kbd{C-c C-c}) to send the message. ! 10123: ! 10124: @table @kbd ! 10125: @item C-x m ! 10126: Begin composing a message to send (@code{mail}). ! 10127: @item C-x 4 m ! 10128: Likewise, but display the message in another window ! 10129: (@code{mail-other-window}). ! 10130: @item C-c C-c ! 10131: In Mail mode, send the message and switch to another buffer ! 10132: (@code{mail-send-and-exit}). ! 10133: @end table ! 10134: ! 10135: @kindex C-x m ! 10136: @findex mail ! 10137: @kindex C-x 4 m ! 10138: @findex mail-other-window ! 10139: The command @kbd{C-x m} (@code{mail}) selects a buffer named ! 10140: @samp{*mail*} and initializes it with the skeleton of an outgoing message. ! 10141: @kbd{C-x 4 m} (@code{mail-other-window}) selects the @samp{*mail*} buffer ! 10142: in a different window, leaving the previous current buffer visible.@refill ! 10143: ! 10144: Because the mail composition buffer is an ordinary Emacs buffer, you can ! 10145: switch to other buffers while in the middle of composing mail, and switch ! 10146: back later (or never). If you use the @kbd{C-x m} command again when you ! 10147: have been composing another message but have not sent it, you are asked to ! 10148: confirm before the old message is erased. If you answer @kbd{n}, the ! 10149: @samp{*mail*} buffer is left selected with its old contents, so you can ! 10150: finish the old message and send it. @kbd{C-u C-x m} is another way to do ! 10151: this. Sending the message marks the @samp{*mail*} buffer ``unmodified'', ! 10152: which avoids the need for confirmation when @kbd{C-x m} is next used. ! 10153: ! 10154: If you are composing a message in the @samp{*mail*} buffer and want to ! 10155: send another message before finishing the first, rename the @samp{*mail*} ! 10156: buffer using @kbd{M-x rename-buffer} (@pxref{Misc Buffer}). ! 10157: ! 10158: @menu ! 10159: * Format: Mail Format. Format of the mail being composed. ! 10160: * Headers: Mail Headers. Details of allowed mail header fields. ! 10161: * Mode: Mail Mode. Special commands for editing mail being composed. ! 10162: @end menu ! 10163: ! 10164: @node Mail Format, Mail Headers, Sending Mail, Sending Mail ! 10165: @section The Format of the Mail Buffer ! 10166: ! 10167: In addition to the @dfn{text} or contents, a message has @dfn{header ! 10168: fields} which say who sent it, when, to whom, why, and so on. Some header ! 10169: fields such as the date and sender are created automatically after the ! 10170: message is sent. Others, such as the recipient names, must be specified by ! 10171: you in order to send the message properly. ! 10172: ! 10173: Mail mode provides a few commands to help you edit some header fields, ! 10174: and some are preinitialized in the buffer automatically at times. You can ! 10175: insert or edit any header fields using ordinary editing commands. ! 10176: ! 10177: The line in the buffer that says ! 10178: ! 10179: @example ! 10180: --text follows this line-- ! 10181: @end example ! 10182: ! 10183: @vindex mail-header-separator ! 10184: @noindent ! 10185: is a special delimiter that separates the headers you have specified from ! 10186: the text. Whatever follows this line is the text of the message; the ! 10187: headers precede it. The delimiter line itself does not appear in the ! 10188: message actually sent. The text used for the delimiter line is controlled ! 10189: by the variable @code{mail-header-separator}. ! 10190: ! 10191: Here is an example of what the headers and text in the @samp{*mail*} buffer ! 10192: might look like. ! 10193: ! 10194: @example ! 10195: To: rms@@mc ! 10196: CC: mly@@mc, rg@@oz ! 10197: Subject: The Emacs Manual ! 10198: --Text follows this line-- ! 10199: Please ignore this message. ! 10200: @end example ! 10201: ! 10202: @node Mail Headers, Mail Mode, Mail Format, Sending Mail ! 10203: @section Mail Header Fields ! 10204: @cindex headers (of mail message) ! 10205: ! 10206: There are several header fields you can use in the @samp{*mail*} buffer. ! 10207: Each header field starts with a field name at the beginning of a line, ! 10208: terminated by a colon. It does not matter whether you use upper or lower ! 10209: case in the field name. After the colon and optional whitespace comes the ! 10210: contents of the field. ! 10211: ! 10212: @table @samp ! 10213: @item To ! 10214: This field contains the mailing addresses to which the message is ! 10215: addressed. ! 10216: ! 10217: @item Subject ! 10218: The contents of the @samp{Subject} field should be a piece of text ! 10219: that says what the message is about. The reason @samp{Subject} fields ! 10220: are useful is that most mail-reading programs can provide a summary of ! 10221: messages, listing the subject of each message but not its text. ! 10222: ! 10223: @item CC ! 10224: This field contains additional mailing addresses to send the message ! 10225: to, but whose readers should not regard the message as addressed to ! 10226: them. ! 10227: ! 10228: @item BCC ! 10229: This field contains additional mailing addresses to send the message ! 10230: to, but which should not appear in the header of the message actually ! 10231: sent. ! 10232: ! 10233: @item FCC ! 10234: This field contains the name of one file (in Unix mail file format) to ! 10235: which a copy of the message should be appended when the message is ! 10236: sent. ! 10237: ! 10238: @item From ! 10239: Use the @samp{From} field to say who you are, when the account you are ! 10240: using to send the mail is not your own. The contents of the ! 10241: @samp{From} field should be a valid mailing address, since replies ! 10242: will normally go there. ! 10243: ! 10244: @item Reply-To ! 10245: Use the @samp{Reply-to} field to direct replies to a different ! 10246: address, not your own. There is no difference between @samp{From} and ! 10247: @samp{Reply-to} in their effect on where replies go, but they convey a ! 10248: different meaning to the human who reads the message. ! 10249: ! 10250: @item In-Reply-To ! 10251: This field contains a piece of text describing a message you are ! 10252: replying to. Some mail systems can use this information to correlate ! 10253: related pieces of mail. Normally this field is filled in by Rmail ! 10254: when you are replying to a message in Rmail, and you never need to ! 10255: think about it (@pxref{Rmail}). ! 10256: @end table ! 10257: ! 10258: @noindent ! 10259: The @samp{To}, @samp{CC}, @samp{BCC} and @samp{FCC} fields can appear ! 10260: any number of times, to specify many places to send the message. ! 10261: ! 10262: @noindent ! 10263: The @samp{To}, @samp{CC}, and @samp{BCC} fields can have continuation ! 10264: lines. All the lines starting with whitespace, following the line on ! 10265: which the field starts, are considered part of the field. For ! 10266: example,@refill ! 10267: ! 10268: @group ! 10269: @example ! 10270: To: foo@@here, this@@there, ! 10271: me@@gnu.cambridge.mass.usa.earth.spiral3281 ! 10272: @end example ! 10273: @end group ! 10274: ! 10275: @noindent ! 10276: If you have a @file{~/.mailrc} file, Emacs will scan it for mail aliases ! 10277: the first time you try to send mail in an Emacs session. Aliases found ! 10278: in the @samp{To}, @samp{CC}, and @samp{BCC} fields will be expanded where ! 10279: appropriate. ! 10280: ! 10281: @vindex mail-archive-file-name ! 10282: If the variable @code{mail-archive-file-name} is non-@code{nil}, it should be a ! 10283: string naming a file; every time you start to edit a message to send, ! 10284: an @samp{FCC} field will be put in for that file. Unless you remove the ! 10285: @samp{FCC} field, every message will be written into that file when it is ! 10286: sent. ! 10287: ! 10288: @node Mail Mode,, Mail Headers, Sending Mail ! 10289: @section Mail Mode ! 10290: ! 10291: The major mode used in the @samp{*mail*} buffer is Mail mode, which is ! 10292: much like Text mode except that various special commands are provided on ! 10293: the @kbd{C-c} prefix. These commands all have to do specifically with ! 10294: editing or sending the message. ! 10295: ! 10296: @table @kbd ! 10297: @item C-c C-s ! 10298: Send the message, and leave the @samp{*mail*} buffer selected ! 10299: (@code{mail-send}). ! 10300: @item C-c C-c ! 10301: Send the message, and select some other buffer (@code{mail-send-and-exit}). ! 10302: @item C-c C-f C-t ! 10303: Move to the @samp{To} header field, creating one if there is none ! 10304: (@code{mail-to}). ! 10305: @item C-c C-f C-s ! 10306: Move to the @samp{Subject} header field, creating one if there is ! 10307: none (@code{mail-subject}). ! 10308: @item C-c C-f C-c ! 10309: Move to the @samp{CC} header field, creating one if there is none ! 10310: (@code{mail-cc}). ! 10311: @item C-c C-w ! 10312: Insert the file @file{~/.signature} at the end of the message text ! 10313: (@code{mail-signature}). ! 10314: @item C-c C-y ! 10315: Yank the selected message from Rmail (@code{mail-yank-original}). ! 10316: This command does nothing unless your command to start sending a ! 10317: message was issued with Rmail. ! 10318: @item C-c C-q ! 10319: Fill all paragraphs of yanked old messages, each individually ! 10320: (@code{mail-fill-yanked-message}). ! 10321: @end table ! 10322: ! 10323: @kindex C-c C-s (Mail mode) ! 10324: @kindex C-c C-c (Mail mode) ! 10325: @findex mail-send ! 10326: @findex mail-send-and-exit ! 10327: There are two ways to send the message. @kbd{C-c C-s} (@code{mail-send}) ! 10328: sends the message and marks the @samp{*mail*} buffer unmodified, but leaves ! 10329: that buffer selected so that you can modify the message (perhaps with new ! 10330: recipients) and send it again. @kbd{C-c C-c} (@code{mail-send-and-exit}) ! 10331: sends and then deletes the window (if there is another window) or switches ! 10332: to another buffer. It puts the @samp{*mail*} buffer at the lowest priority ! 10333: for automatic reselection, since you are finished with using it. This is ! 10334: the usual way to send the message. ! 10335: ! 10336: @kindex C-c C-f C-t (Mail mode) ! 10337: @findex mail-to ! 10338: @kindex C-c C-f C-s (Mail mode) ! 10339: @findex mail-subject ! 10340: @kindex C-c C-f C-c (Mail mode) ! 10341: @findex mail-cc ! 10342: Mail mode provides some other special commands that are useful for ! 10343: editing the headers and text of the message before you send it. There are ! 10344: three commands defined to move point to particular header fields, all based ! 10345: on the prefix @kbd{C-c C-f} (@samp{C-f} is for ``field''). They are ! 10346: @kbd{C-c C-f C-t} (@code{mail-to}) to move to the @samp{To} field, @kbd{C-c ! 10347: C-f C-s} (@code{mail-subject}) for the @samp{Subject} field, and @kbd{C-c ! 10348: C-f C-c} (@code{mail-cc}) for the @samp{CC} field. These fields have ! 10349: special motion commands because they are the most common fields for the ! 10350: user to want to edit. ! 10351: ! 10352: @kindex C-c C-w (Mail mode) ! 10353: @findex mail-signature ! 10354: @kbd{C-c C-w} (@code{mail-signature}) adds a standard piece text at the end of the ! 10355: message to say more about who you are. The text comes from the file ! 10356: @file{.signature} in your home directory. ! 10357: ! 10358: @kindex C-c C-y (Mail mode) ! 10359: @findex mail-yank-original ! 10360: When mail sending is invoked from the Rmail mail reader using an Rmail ! 10361: command, @kbd{C-c C-y} can be used inside the @samp{*mail*} buffer to insert ! 10362: the text of the message you are replying to. Normally it indents each line ! 10363: of that message four spaces and eliminates most header fields. A numeric ! 10364: argument specifies the number of spaces to indent. An argument of just ! 10365: @kbd{C-u} says not to indent at all and not to eliminate anything. ! 10366: @kbd{C-c C-y} always uses the current message from the @samp{RMAIL} buffer, ! 10367: so you can insert several old messages by selecting one in @samp{RMAIL}, ! 10368: switching to @samp{*mail*} and yanking it, then switching back to ! 10369: @samp{RMAIL} to select another.@refill ! 10370: ! 10371: @kindex C-c C-q (Mail mode) ! 10372: @findex mail-fill-yanked-message ! 10373: After using @kbd{C-c C-y}, the command @kbd{C-c C-q} (@code{mail-fill-yanked-message}) can ! 10374: be used to fill the paragraphs of the yanked old message or messages. One ! 10375: use of @kbd{C-c C-q} fills all such paragraphs, each one separately. ! 10376: ! 10377: @vindex mail-mode-hook ! 10378: Turning on Mail mode (which @kbd{C-x m} does automatically) calls the ! 10379: value of @code{text-mode-hook}, if it is not void or @code{nil}, and then calls ! 10380: the value of @code{mail-mode-hook} if that is not void or @code{nil}. ! 10381: ! 10382: @node Rmail, Recursive Edit, Sending Mail, Top ! 10383: @chapter Reading Mail with Rmail ! 10384: @cindex Rmail ! 10385: @cindex message ! 10386: @findex rmail ! 10387: ! 10388: Rmail is an Emacs subsystem for reading and disposing of mail that you ! 10389: receive. Rmail stores mail messages in files called Rmail files. Reading ! 10390: the message in an Rmail file is done in a special major mode, Rmail mode, ! 10391: which redefines most letters to run commands for managing mail. To enter ! 10392: Rmail, type @kbd{M-x rmail}. This reads your primary mail file, merges ! 10393: new mail in from your inboxes, displays the first new message, and lets ! 10394: you begin reading. ! 10395: ! 10396: @cindex primary mail file ! 10397: Using Rmail in the simplest fashion, you have one Rmail file @file{~/RMAIL} ! 10398: in which all of your mail is saved. It is called your @dfn{primary mail ! 10399: file}. In more sophisticated usage, you can copy messages into other Rmail ! 10400: files and then edit those files with Rmail. ! 10401: ! 10402: Rmail displays only one message at a time. It is called the @dfn{current ! 10403: message}. Rmail mode's special commands can do such things as move to ! 10404: another message, delete the message, copy the message into another file, or ! 10405: send a reply. ! 10406: ! 10407: @cindex message number ! 10408: Within the Rmail file, messages are arranged sequentially in order ! 10409: of receipt. They are also assigned consecutive integers as their ! 10410: @dfn{message numbers}. The number of the current message is displayed ! 10411: in Rmail's mode line, followed by the total number of messages in the ! 10412: file. You can move to a message by specifying its message number ! 10413: using the @kbd{j} key (@pxref{Rmail Motion}). ! 10414: ! 10415: @kindex s (Rmail) ! 10416: @findex rmail-save ! 10417: Following the usual conventions of Emacs, changes in an Rmail file become ! 10418: permanent only when the file is saved. You can do this with @kbd{s} ! 10419: (@code{rmail-save}), which also expunges deleted messages from the file ! 10420: first (@pxref{Rmail Deletion}). To save the file without expunging, use ! 10421: @kbd{C-x C-s}. Rmail saves the Rmail file spontaneously when moving new ! 10422: mail from an inbox file (@pxref{Rmail Inbox}). ! 10423: ! 10424: @kindex q (Rmail) ! 10425: @findex rmail-quit ! 10426: You can exit Rmail with @kbd{q} (@code{rmail-quit}); this expunges and saves the ! 10427: Rmail file and then switches to another buffer. But there is no need to ! 10428: `exit' formally. If you switch from Rmail to editing in other buffers, and ! 10429: never happen to switch back, you have exited. Just make sure to save the ! 10430: Rmail file eventually (like any other file you have changed). @kbd{C-x s} ! 10431: is a good enough way to do this (@pxref{Saving}). ! 10432: ! 10433: @menu ! 10434: * Scroll: Rmail Scrolling. Scrolling through a message. ! 10435: * Motion: Rmail Motion. Moving to another message. ! 10436: * Deletion: Rmail Deletion. Deleting and expunging messages. ! 10437: * Inbox: Rmail Inbox. How mail gets into the Rmail file. ! 10438: * Files: Rmail Files. Using multiple Rmail files. ! 10439: * Output: Rmail Output. Copying message out to files. ! 10440: * Labels: Rmail Labels. Classifying messages by labeling them. ! 10441: * Summary: Rmail Summary. Summaries show brief info on many messages. ! 10442: * Reply: Rmail Reply. Sending replies to messages you are viewing. ! 10443: * Editing: Rmail Editing. Editing message text and headers in Rmail. ! 10444: * Digest: Rmail Digest. Extracting the messages from a digest message. ! 10445: @end menu ! 10446: ! 10447: @node Rmail Scrolling, Rmail Motion, Rmail, Rmail ! 10448: @section Scrolling Within a Message ! 10449: ! 10450: When Rmail displays a message that does not fit on the screen, it is ! 10451: necessary to scroll through it. This could be done with @kbd{C-v}, @kbd{M-v} ! 10452: and @kbd{M-<}, but in Rmail scrolling is so frequent that it deserves to be ! 10453: easier to type. ! 10454: ! 10455: @table @kbd ! 10456: @item @key{SPC} ! 10457: Scroll forward (@code{scroll-up}). ! 10458: @item @key{DEL} ! 10459: Scroll backward (@code{scroll-down}). ! 10460: @item . ! 10461: Scroll to start of message (@code{rmail-beginning-of-message}). ! 10462: @end table ! 10463: ! 10464: @kindex SPC (Rmail) ! 10465: @kindex DEL (Rmail) ! 10466: Since the most common thing to do while reading a message is to scroll ! 10467: through it by screenfuls, Rmail makes @key{SPC} and @key{DEL} synonyms of ! 10468: @kbd{C-v} (@code{scroll-up}) and @kbd{M-v} (@code{scroll-down}) ! 10469: ! 10470: @kindex . (Rmail) ! 10471: @findex rmail-beginning-of-message ! 10472: The command @kbd{.} (@code{rmail-beginning-of-message}) scrolls back to the ! 10473: beginning of the selected message. This is not quite the same as @kbd{M-<}: ! 10474: for one thing, it does not set the mark; for another, it resets the buffer ! 10475: boundaries to the current message if you have changed them. ! 10476: ! 10477: @node Rmail Motion, Rmail Deletion, Rmail Scrolling, Rmail ! 10478: @section Moving Among Messages ! 10479: ! 10480: The most basic thing to do with a message is to read it. The way to do ! 10481: this in Rmail is to make the message current. You can make any message ! 10482: current given its message number using the @kbd{j} command, but the usual ! 10483: thing to do is to move sequentially through the file, since this is the ! 10484: order of receipt of messages. When you enter Rmail, you are positioned at ! 10485: the first new message (new messages are those received since the previous ! 10486: use of Rmail), or at the last message if there are no new messages this ! 10487: time. Move forward to see the other new messages; move backward to ! 10488: reexamine old messages. ! 10489: ! 10490: @table @kbd ! 10491: @item n ! 10492: Move to the next nondeleted message, skipping any intervening deleted @* ! 10493: messages (@code{rmail-next-undeleted-message}). ! 10494: @item p ! 10495: Move to the previous nondeleted message @* ! 10496: (@code{rmail-previous-undeleted-message}). ! 10497: @item M-n ! 10498: Move to the next message, including deleted messages ! 10499: (@code{rmail-next-message}). ! 10500: @item M-p ! 10501: Move to the previous message, including deleted messages ! 10502: (@code{rmail-previous-message}). ! 10503: @item j ! 10504: Move to the first message. With argument @var{n}, move to ! 10505: message number @var{n} (@code{rmail-show-message}). ! 10506: @item > ! 10507: Move to the last message (@code{rmail-last-message}). ! 10508: ! 10509: @item M-s @var{regexp} @key{RET} ! 10510: Move to the next message containing a match for @var{regexp} ! 10511: (@code{rmail-search}). If @var{regexp} is empty, the last regexp used is ! 10512: used again. ! 10513: ! 10514: @item - M-s @var{regexp} @key{RET} ! 10515: Move to the previous message containing a match for @var{regexp}. ! 10516: If @var{regexp} is empty, the last regexp used is used again. ! 10517: @end table ! 10518: ! 10519: @kindex n (Rmail) ! 10520: @kindex p (Rmail) ! 10521: @kindex M-n (Rmail) ! 10522: @kindex M-p (Rmail) ! 10523: @findex rmail-next-undeleted-message ! 10524: @findex rmail-previous-undeleted-message ! 10525: @findex rmail-next-message ! 10526: @findex rmail-previous-message ! 10527: @kbd{n} and @kbd{p} are the usual way of moving among messages in Rmail. They ! 10528: move through the messages sequentially, but skip over deleted messages, ! 10529: which is usually what you want to do. Their command definitions are named ! 10530: @code{rmail-next-undeleted-message} and @code{rmail-previous-undeleted-message}. If ! 10531: you do not want to skip deleted messages---for example, if you want to move ! 10532: to a message to undelete it---use the variants @kbd{M-n} and @kbd{M-p} ! 10533: (@code{rmail-next-message} and @code{rmail-previous-message}). A numeric ! 10534: argument to any of these commands serves as a repeat count.@refill ! 10535: ! 10536: In Rmail, you can specify a numeric argument by typing the digits. ! 10537: It is not necessary to type @kbd{C-u} first. ! 10538: ! 10539: @kindex M-s (Rmail) ! 10540: @findex rmail-search ! 10541: The @kbd{M-s} (@code{rmail-search}) command is Rmail's version of search. The ! 10542: usual incremental search command @kbd{C-s} works in Rmail, but it searches ! 10543: only within the current message. The purpose of @kbd{M-s} is to search for ! 10544: another message. It reads a regular expression (@pxref{Regexps}) ! 10545: nonincrementally, then searches starting at the beginning of the following ! 10546: message for a match. The message containing the match is selected. ! 10547: ! 10548: To search backward in the file for another message, give @kbd{M-s} a ! 10549: negative argument. In Rmail this can be done with @kbd{- M-s}. ! 10550: ! 10551: It is also possible to search for a message based on labels. ! 10552: @xref{Rmail Labels}. ! 10553: ! 10554: @kindex j (Rmail) ! 10555: @kindex > (Rmail) ! 10556: @findex rmail-show-message ! 10557: @findex rmail-last-message ! 10558: To move to a message specified by absolute message number, use @kbd{j} ! 10559: (@code{rmail-show-message}) with the message number as argument. With no ! 10560: argument, @kbd{j} selects the first message. @kbd{>} (@code{rmail-last-message}) selects ! 10561: the last message. ! 10562: ! 10563: @node Rmail Deletion, Rmail Inbox, Rmail Motion, Rmail ! 10564: @section Deleting Messages ! 10565: ! 10566: @cindex deletion (Rmail) ! 10567: When you no longer need to keep a message, you can @dfn{delete} it. This ! 10568: flags it as ignorable, and some Rmail commands will pretend it is no longer ! 10569: present; but it still has its place in the Rmail file, and still has its ! 10570: message number. ! 10571: ! 10572: @cindex expunging (Rmail) ! 10573: @dfn{Expunging} the Rmail file actually removes the deleted messages. ! 10574: The remaining messages are renumbered consecutively. Expunging is the only ! 10575: action that changes the message number of any message, except for ! 10576: undigestifying (@pxref{Rmail Digest}). ! 10577: ! 10578: @table @kbd ! 10579: @item d ! 10580: Delete the current message, and move to the next nondeleted message ! 10581: (@code{rmail-delete-forward}). ! 10582: @item C-d ! 10583: Delete the current message, and move to the previous nondeleted ! 10584: message (@code{rmail-delete-backward}). ! 10585: @item u ! 10586: Undelete the current message, or move back to a deleted message and ! 10587: undelete it (@code{rmail-undelete-previous-message}). ! 10588: @itemx x ! 10589: @item e ! 10590: Expunge the Rmail file (@code{rmail-expunge}). These two ! 10591: commands are synonyms. ! 10592: @end table ! 10593: ! 10594: @kindex d (Rmail) ! 10595: @kindex C-d (Rmail) ! 10596: @findex rmail-delete-forward ! 10597: @findex rmail-delete-backward ! 10598: There are two Rmail commands for deleting messages. Both delete the ! 10599: current message and select another message. @kbd{d} (@code{rmail-delete-forward}) ! 10600: moves to the following message, skipping messages already deleted, while ! 10601: @kbd{C-d} (@code{rmail-delete-backward}) moves to the previous nondeleted message. ! 10602: If there is no nondeleted message to move to in the specified direction, ! 10603: the message that was just deleted remains current. ! 10604: ! 10605: @cindex undeletion (Rmail) ! 10606: @kindex e (Rmail) ! 10607: @findex rmail-expunge ! 10608: To make all the deleted messages finally vanish from the Rmail file, ! 10609: type @kbd{e} (@code{rmail-expunge}). Until you do this, you can still @dfn{undelete} ! 10610: the deleted messages. ! 10611: ! 10612: @kindex u (Rmail) ! 10613: @findex rmail-undelete-previous-message ! 10614: To undelete, type ! 10615: @kbd{u} (@code{rmail-undelete-previous-message}), which is designed to cancel the ! 10616: effect of a @kbd{d} command (usually). It undeletes the current message ! 10617: if the current message is deleted. Otherwise it moves backward to previous ! 10618: messages until a deleted message is found, and undeletes that message. ! 10619: ! 10620: You can usually undo a @kbd{d} with a @kbd{u} because the @kbd{u} moves ! 10621: back to and undeletes the message that the @kbd{d} deleted. But this does ! 10622: not work when the @kbd{d} skips a few already-deleted messages that follow ! 10623: the message being deleted; then the @kbd{u} command will undelete the last ! 10624: of the messages that were skipped. There is no clean way to avoid this ! 10625: problem. However, by repeating the @kbd{u} command, you can eventually get ! 10626: back to the message that you intended to undelete. You can also reach that ! 10627: message with @kbd{M-p} commands and then type @kbd{u}.@refill ! 10628: ! 10629: A deleted message has the @samp{deleted} attribute, and as a result ! 10630: @samp{deleted} appears in the mode line when the current message is ! 10631: deleted. In fact, deleting or undeleting a message is nothing more than ! 10632: adding or removing this attribute. @xref{Rmail Labels}. ! 10633: ! 10634: @node Rmail Inbox, Rmail Files, Rmail Deletion, Rmail ! 10635: @section Rmail Files and Inboxes ! 10636: @cindex inbox file ! 10637: ! 10638: Unix places incoming mail for you in a file that we call your @dfn{inbox}. ! 10639: When you start up Rmail, it copies the new messages from your inbox into ! 10640: your primary mail file, an Rmail file, which also contains other messages ! 10641: saved from previous Rmail sessions. It is in this file that you actually ! 10642: read the mail with Rmail. This operation is called @dfn{getting new mail}. ! 10643: It can be repeated at any time using the @kbd{g} key in Rmail. The inbox ! 10644: file name is @file{/usr/spool/mail/@var{username}} in Berkeley Unix, ! 10645: @file{/usr/mail/@var{username}} in system V. ! 10646: ! 10647: There are two reason for having separate Rmail files and inboxes. ! 10648: ! 10649: @enumerate ! 10650: @item ! 10651: The format in which Unix delivers the mail in the inbox is not ! 10652: adequate for Rmail mail storage. It has no way to record attributes ! 10653: (such as @samp{deleted}) or user-specified labels; it has no way to record ! 10654: old headers and reformatted headers; it has no way to record cached ! 10655: summary line information. ! 10656: ! 10657: @item ! 10658: It is very cumbersome to access an inbox file without danger of losing ! 10659: mail, because it is necessary to interlock with mail delivery. ! 10660: Moreover, different Unix systems use different interlocking ! 10661: techniques. The strategy of moving mail out of the inbox once and for ! 10662: all into a separate Rmail file avoids the need for interlocking in all ! 10663: the rest of Rmail, since only Rmail operates on the Rmail file. ! 10664: @end enumerate ! 10665: ! 10666: When getting new mail, Rmail first copies the new mail from the inbox ! 10667: file to the Rmail file; then it saves the Rmail file; then it deletes the ! 10668: inbox file. This way, a system crash may cause duplication of mail between ! 10669: the inbox and the Rmail file, but cannot lose mail. ! 10670: ! 10671: Copying mail from an inbox in the system's mailer directory actually puts ! 10672: it in an intermediate file @file{~/.newmail}. This is because the ! 10673: interlocking is done by a C program that copies to another file. ! 10674: @file{~/.newmail} is deleted after mail merging is successful. If there is ! 10675: a crash at the wrong time, this file will continue to exist and will be ! 10676: used as an inbox the next time you get new mail. ! 10677: ! 10678: @node Rmail Files, Rmail Output, Rmail Inbox, Rmail ! 10679: @section Multiple Mail Files ! 10680: ! 10681: Rmail operates by default on your @dfn{primary mail file}, which is named ! 10682: @file{~/RMAIL} and receives your incoming mail from your system inbox file. ! 10683: But you can also have other mail files and edit them with Rmail. These ! 10684: files can receive mail through their own inboxes, or you can move messages ! 10685: into them by explicit command in Rmail (@pxref{Rmail Output}). ! 10686: ! 10687: @table @kbd ! 10688: @item i @var{file} @key{RET} ! 10689: Read @var{file} into Emacs and run Rmail on it (@code{rmail-input}). ! 10690: ! 10691: @item M-x set-rmail-inbox-list @key{RET} @var{files} @key{RET} ! 10692: Specify inbox file names for current Rmail file to get mail from. ! 10693: ! 10694: @item g ! 10695: Merge new mail from current Rmail file's inboxes ! 10696: (@code{rmail-get-new-mail}). ! 10697: ! 10698: @item C-u g @var{file} ! 10699: Merge new mail from inbox file @var{file}. ! 10700: @end table ! 10701: ! 10702: @kindex i (Rmail) ! 10703: @findex rmail-input ! 10704: To run Rmail on a file other than your primary mail file, you may use the ! 10705: @kbd{i} (@code{rmail-input}) command in Rmail. This visits the file, puts it in ! 10706: Rmail mode, and then gets new mail from the file's inboxes if any. ! 10707: You can also use @kbd{M-x rmail-input} even when not in Rmail. ! 10708: ! 10709: The file you read with @kbd{i} does not have to be in Rmail file format. ! 10710: It could also be Unix mail format, or mmdf format; or it could be a mixture ! 10711: of all three, as long as each message belongs to one of the three formats. ! 10712: Rmail recognizes all three and converts all the messages to proper Rmail ! 10713: format before showing you the file. ! 10714: ! 10715: @findex set-rmail-inbox-list ! 10716: Each Rmail file can contain a list of inbox file names; you can specify ! 10717: this list with @kbd{M-x set-rmail-inbox-list @key{RET} @var{files} ! 10718: @key{RET}}. The argument can contain any number of file names, separated ! 10719: by commas. It can also be empty, which specifies that this file should ! 10720: have no inboxes. Once a list of inboxes is specified, the Rmail file ! 10721: remembers it permanently until it is explicitly changed.@refill ! 10722: ! 10723: @kindex g (Rmail) ! 10724: @findex rmail-get-new-mail ! 10725: If an Rmail file has inboxes, new mail is merged in from the inboxes when ! 10726: the Rmail file is brought into Rmail, and when the @kbd{g} (@code{rmail-get-new-mail}) ! 10727: command is used. If the Rmail file specifies no inboxes, then no new mail ! 10728: is merged in at these times. A special exception is made for your primary ! 10729: mail file in using the standard system inbox for it if it does not specify ! 10730: any. ! 10731: ! 10732: To merge mail from a file that is not the usual inbox, give the @kbd{g} ! 10733: key a numeric argument, as in @kbd{C-u g}. Then it reads a file name and ! 10734: merges mail from that file. The inbox file is not deleted or changed in ! 10735: any way when @kbd{g} with an argument is used. This is, therefore, a ! 10736: general way of merging one file of messages into another. ! 10737: ! 10738: @node Rmail Output, Rmail Labels, Rmail Files, Rmail ! 10739: @section Copying Messages Out to Files ! 10740: ! 10741: @table @kbd ! 10742: @item o @var{file} @key{RET} ! 10743: Append a copy of the current message to the file @var{file}, ! 10744: writing it in Rmail file format (@code{rmail-output-to-rmail-file}). ! 10745: ! 10746: @item C-o @var{file} @key{RET} ! 10747: Append a copy of the current message to the file @var{file}, ! 10748: writing it in Unix mail file format (@code{rmail-output}). ! 10749: @end table ! 10750: ! 10751: @kindex o (Rmail) ! 10752: @findex rmail-output-to-rmail-file ! 10753: @kindex C-o (Rmail) ! 10754: @findex rmail-output ! 10755: If an Rmail file has no inboxes, how does it get anything in it? By ! 10756: explicit @kbd{o} commands. ! 10757: ! 10758: @kbd{o} (@code{rmail-output-to-rmail-file}) appends the current message ! 10759: in Rmail format to the end of the specified file. This is the best command ! 10760: to use to move messages between Rmail files. If the other Rmail file is ! 10761: currently visited, the copying is done into the other file's Emacs buffer ! 10762: instead. You should eventually save it on disk. ! 10763: ! 10764: The @kbd{C-o} (@code{rmail-output}) command in Rmail appends a copy of the current ! 10765: message to a specified file, in Unix mail file format. This is useful for ! 10766: moving messages into files to be read by other mail processors that do not ! 10767: understand Rmail format. ! 10768: ! 10769: Copying a message with @kbd{o} or @kbd{C-o} gives the original copy of the ! 10770: message the @samp{filed} attribute, so that @samp{filed} appears in the mode ! 10771: line when such a message is current. ! 10772: ! 10773: Normally you should use only @kbd{o} to output messages to other Rmail ! 10774: files, never @kbd{C-o}. But it is also safe if you always use @kbd{C-o}, ! 10775: never @kbd{o}. When a file is visited in Rmail, the last message is ! 10776: checked, and if it is in Unix format, the entire file is scanned and all ! 10777: Unix-format messages are converted to Rmail format. (The reason for ! 10778: checking the last message is that scanning the file is slow and most Rmail ! 10779: files have only Rmail format messages.) If you use @kbd{C-o} consistently, ! 10780: the last message is sure to be in Unix format, so Rmail will convert all ! 10781: messages properly. ! 10782: ! 10783: The case where you might want to use @kbd{C-o} always, instead of @kbd{o} ! 10784: always, is when you or other users want to append mail to the same file ! 10785: from other mail processors. Other mail processors probably do not know ! 10786: Rmail format but do know Unix format. ! 10787: ! 10788: In any case, always use @kbd{o} to add to an Rmail file that is being ! 10789: visited in Rmail. Adding messages with @kbd{C-o} to the actual disk file ! 10790: will trigger a ``simultaneous editing'' warning when you ask to save the ! 10791: Emacs buffer, and will be lost if you do save. ! 10792: ! 10793: @node Rmail Labels, Rmail Summary, Rmail Output, Rmail ! 10794: @section Labels ! 10795: @cindex label (Rmail) ! 10796: @cindex attribute (Rmail) ! 10797: ! 10798: Each message can have various @dfn{labels} assigned to it as a means of ! 10799: classification. A label has a name; different names mean different labels. ! 10800: Any given label is either present or absent on a particular message. A few ! 10801: label names have standard meanings and are given to messages automatically ! 10802: by Rmail when appropriate; these special labels are called @dfn{attributes}. ! 10803: All other labels are assigned by the user. ! 10804: ! 10805: @table @kbd ! 10806: @item a @var{label} @key{RET} ! 10807: Assign the label @var{label} to the current message (@code{rmail-add-label}). ! 10808: @item k @var{label} @key{RET} ! 10809: Remove the label @var{label} from the current message (@code{rmail-kill-label}). ! 10810: @item C-M-n @var{labels} @key{RET} ! 10811: Move to the next message that has one of the labels @var{labels} ! 10812: (@code{rmail-next-labeled-message}). ! 10813: @item C-M-p @var{labels} @key{RET} ! 10814: Move to the previous message that has one of the labels @var{labels} ! 10815: (@code{rmail-previous-labeled-message}). ! 10816: @item C-M-l @var{labels} @key{RET} ! 10817: Make a summary of all messages containing any of the labels @var{labels} ! 10818: (@code{rmail-summary-by-labels}). ! 10819: @end table ! 10820: ! 10821: @noindent ! 10822: Specifying an empty string for one these commands means to use the last ! 10823: label specified for any of these commands. ! 10824: ! 10825: @kindex a (Rmail) ! 10826: @kindex k (rmail) ! 10827: @findex rmail-add-label ! 10828: @findex rmail-kill-label ! 10829: The @kbd{a} (@code{rmail-add-label}) and @kbd{k} (@code{rmail-kill-label}) commands allow ! 10830: you to assign or remove any label on the current message. If the @var{label} ! 10831: argument is empty, it means to assign or remove the same label most ! 10832: recently assigned or removed. ! 10833: ! 10834: Once you have given messages labels to classify them as you wish, there ! 10835: are two ways to use the labels: in moving and in summaries. ! 10836: ! 10837: @kindex C-M-n (Rmail) ! 10838: @kindex C-M-p (Rmail) ! 10839: @findex rmail-next-labeled-message ! 10840: @findex rmail-previous-labeled-message ! 10841: The command @kbd{C-M-n @var{labels} @key{RET}} ! 10842: (@code{rmail-next-labeled-message}) moves to the next message that has one ! 10843: of the labels @var{labels}. @var{labels} is one or more label names, ! 10844: separated by commas. @kbd{C-M-p} (@code{rmail-previous-labeled-message}) ! 10845: is similar, but moves backwards to previous messages. A preceding numeric ! 10846: argument to either one serves as a repeat count.@refill ! 10847: ! 10848: @kindex C-M-l (Rmail) ! 10849: @findex rmail-summary-by-labels ! 10850: The command @kbd{C-M-l @var{labels} @key{RET}} ! 10851: (@code{rmail-summary-by-labels}) displays a summary containing only the ! 10852: messages that have at least one of a specified set of messages. The ! 10853: argument @var{labels} is one or more label names, separated by commas. ! 10854: @xref{Rmail Summary}, for information on summaries.@refill ! 10855: ! 10856: If the @var{labels} argument to @kbd{C-M-n}, @kbd{C-M-p} or @kbd{C-M-l} is empty, it means ! 10857: to use the last set of labels specified for any of these commands. ! 10858: ! 10859: Some labels such as @samp{deleted} and @samp{filed} have built-in meanings and ! 10860: are assigned to or removed from messages automatically at appropriate ! 10861: times; these labels are called @dfn{attributes}. Here is a list of Rmail ! 10862: attributes: ! 10863: ! 10864: @table @samp ! 10865: @item unseen ! 10866: Means the message has never been current. Assigned to messages when ! 10867: they come from an inbox file, and removed when a message is made ! 10868: current. ! 10869: @item deleted ! 10870: Means the message is deleted. Assigned by deletion commands and ! 10871: removed by undeletion commands (@pxref{Rmail Deletion}). ! 10872: @item filed ! 10873: Means the message has been copied to some other file. Assigned by the ! 10874: file output commands (@pxref{Rmail Files}). ! 10875: @item answered ! 10876: Means you have mailed an answer to the message. Assigned by the @kbd{r} ! 10877: command (@code{rmail-reply}). @xref{Rmail Reply}. ! 10878: @item forwarded ! 10879: Means you have forwarded the message to other users. Assigned by the ! 10880: @kbd{f} command (@code{rmail-forward}). @xref{Rmail Reply}. ! 10881: @item edited ! 10882: Means you have edited the text of the message within Rmail. ! 10883: @xref{Rmail Editing}. ! 10884: @end table ! 10885: ! 10886: All other labels are assigned or removed only by the user, and it is up ! 10887: to the user to decide what they mean. ! 10888: ! 10889: @node Rmail Summary, Rmail Reply, Rmail Labels, Rmail ! 10890: @section Summaries ! 10891: @cindex summary (Rmail) ! 10892: ! 10893: A @dfn{summary} is a buffer containing one line per message that Rmail ! 10894: can make and display to give you an overview of the mail in an Rmail file. ! 10895: Each line shows the message number, the sender, the labels, and the ! 10896: subject. When the summary buffer is selected, various commands can be used ! 10897: to select messages by moving in the summary buffer, or delete or undelete ! 10898: messages. ! 10899: ! 10900: A summary buffer applies to a single Rmail file only; if you are ! 10901: editing multiple Rmail files, they have separate summary buffers. The ! 10902: summary buffer name is made by appending @samp{-summary} to the Rmail buffer's ! 10903: name. Only one summary buffer will be displayed at a time unless you make ! 10904: several windows and select the summary buffers by hand. ! 10905: ! 10906: @menu ! 10907: * Rmail Make Summary:: Making various sorts of summaries. ! 10908: * Rmail Summary Edit:: Manipulating messages from the summary. ! 10909: @end menu ! 10910: ! 10911: @node Rmail Make Summary, Rmail Summary Edit, Rmail Summary, Rmail Summary ! 10912: @subsection Making Summaries ! 10913: ! 10914: Here are the commands to create a summary for the current Rmail file. ! 10915: Summaries do not update automatically; to make an updated summary, you ! 10916: must use one of these commands again. ! 10917: ! 10918: @table @kbd ! 10919: @item h ! 10920: @itemx C-M-h ! 10921: Summarize all messages (@code{rmail-summary}). ! 10922: @item l @var{labels} @key{RET} ! 10923: @itemx C-M-l @var{labels} @key{RET} ! 10924: Summarize message that have one or more of the specified labels ! 10925: (@code{rmail-summary-by-labels}). ! 10926: @item C-M-r @var{rcpts} @key{RET} ! 10927: Summarize messages that have one or more of the specified recipients ! 10928: (@code{rmail-summary-by-recipients}) ! 10929: @end table ! 10930: ! 10931: @kindex h (Rmail) ! 10932: @findex rmail-summary ! 10933: The @kbd{h} or @kbd{C-M-h} (@code{rmail-summary}) command fills the summary buffer ! 10934: for the current Rmail file with a summary of all the messages in the file. ! 10935: It then displays and selects the summary buffer in another window. ! 10936: ! 10937: @kindex l (Rmail) ! 10938: @kindex C-M-l (Rmail) ! 10939: @findex rmail-summary-by-labels ! 10940: @kbd{C-M-l @var{labels} @key{RET}} (@code{rmail-summary-by-labels}) makes ! 10941: a partial summary mentioning only the messages that have one or more of the ! 10942: labels @var{labels}. @var{labels} should contain label names separated by ! 10943: commas.@refill ! 10944: ! 10945: @kindex C-M-r (Rmail) ! 10946: @findex rmail-summary-by-recipients ! 10947: @kbd{C-M-r @var{rcpts} @key{RET}} (@code{rmail-summary-by-recipients}) ! 10948: makes a partial summary mentioning only the messages that have one or more ! 10949: of the recipients @var{rcpts}. @var{rcpts} should contain mailing ! 10950: addresses separated by commas.@refill ! 10951: ! 10952: Note that there is only one summary buffer for any Rmail file; making one ! 10953: kind of summary discards any previously made summary. ! 10954: ! 10955: @node Rmail Summary Edit,, Rmail Make Summary, Rmail Summary ! 10956: @subsection Editing in Summaries ! 10957: ! 10958: Summary buffers are given the major mode Rmail Summary mode, which ! 10959: provides the following special commands: ! 10960: ! 10961: @table @kbd ! 10962: @item j ! 10963: Select the message described by the line that point is on ! 10964: (@code{rmail-summary-goto-msg}). ! 10965: @item C-n ! 10966: Move to next line and select its message in Rmail ! 10967: (@code{rmail-summary-next-all}). ! 10968: @item C-p ! 10969: Move to previous line and select its message ! 10970: (@code{rmail-summary-previous-all}). ! 10971: @item n ! 10972: Move to next line, skipping lines saying `deleted', and select its ! 10973: message (@code{rmail-summary-next-msg}). ! 10974: @item p ! 10975: Move to previous line, skipping lines saying `deleted', and select ! 10976: its message (@code{rmail-summary-previous-msg}). ! 10977: @item d ! 10978: Delete the current line's message, then do like @kbd{n} ! 10979: (@code{rmail-summary-delete-forward}). ! 10980: @item u ! 10981: Undelete and select this message or the previous deleted message in ! 10982: the summary (@code{rmail-summary-undelete}). ! 10983: @item @key{SPC} ! 10984: Scroll the other window (presumably Rmail) forward ! 10985: (@code{rmail-summary-scroll-msg-up}). ! 10986: @item @key{DEL} ! 10987: Scroll the other window backward (@code{rmail-summary-scroll-msg-down}). ! 10988: @item x ! 10989: Kill the summary window (@code{rmail-summary-exit}). ! 10990: @item q ! 10991: Exit Rmail (@code{rmail-summary-quit}). ! 10992: @end table ! 10993: ! 10994: @kindex C-n (Rmail summary) ! 10995: @kindex C-p (Rmail summary) ! 10996: @findex rmail-summary-next-all ! 10997: @findex rmail-summary-previous-all ! 10998: The keys @kbd{C-n} and @kbd{C-p} are modified in Rmail Summary mode so that in ! 10999: addition to moving point in the summary buffer they also cause the line's ! 11000: message to become current in the associated Rmail buffer. That buffer is ! 11001: also made visible in another window if it is not already so. ! 11002: ! 11003: @kindex n (Rmail summary) ! 11004: @kindex p (Rmail summary) ! 11005: @findex rmail-summary-next-msg ! 11006: @findex rmail-summary-previous-msg ! 11007: @kbd{n} and @kbd{p} are similar to @kbd{C-n} and @kbd{C-p}, but skip ! 11008: lines that say `message deleted'. They are like the @kbd{n} and @kbd{p} ! 11009: keys of Rmail itself. Note, however, that in a partial summary these ! 11010: commands move only among the message listed in the summary.@refill ! 11011: ! 11012: @kindex j (Rmail summary) ! 11013: @findex rmail-summary-goto-msg ! 11014: The other Emacs cursor motion commands are not changed in Rmail Summary ! 11015: mode, so it is easy to get the point on a line whose message is not ! 11016: selected in Rmail. This can also happen if you switch to the Rmail window ! 11017: and switch messages there. To get the Rmail buffer back in sync with the ! 11018: summary, use the @kbd{j} (@code{rmail-summary-goto-msg}) command, which selects ! 11019: in Rmail the message of the current summary line. ! 11020: ! 11021: @kindex d (Rmail summary) ! 11022: @kindex u (Rmail summary) ! 11023: @findex rmail-summary-delete-forward ! 11024: @findex rmail-summary-undelete ! 11025: Deletion and undeletion can also be done from the summary buffer. They ! 11026: always work based on where point is located in the summary buffer, ignoring ! 11027: which message is selected in Rmail. @kbd{d} (@code{rmail-summary-delete-forward}) ! 11028: deletes the current line's message, then moves to the next line whose ! 11029: message is not deleted and selects that message. The inverse of this is ! 11030: @kbd{u} (@code{rmail-summary-undelete}), which moves back (if necessary) to a line ! 11031: whose message is deleted, undeletes that message, and selects it in Rmail. ! 11032: ! 11033: @kindex SPC (Rmail summary) ! 11034: @kindex DEL (Rmail summary) ! 11035: @findex rmail-summary-scroll-msg-down ! 11036: @findex rmail-summary-scroll-msg-up ! 11037: When moving through messages with the summary buffer, it is convenient to ! 11038: be able to scroll the message while remaining in the summary window. ! 11039: The commands @key{SPC} (@code{rmail-summary-scroll-msg-up}) and @key{DEL} ! 11040: (@code{rmail-summary-scroll-msg-down}) do this. They scroll the message just ! 11041: as those same keys do when the Rmail buffer is selected.@refill ! 11042: ! 11043: @kindex x (Rmail summary) ! 11044: @findex rmail-summary-exit ! 11045: When you are finished using the summary, type @kbd{x} (@code{rmail-summary-exit}) ! 11046: to kill the summary buffer's window. ! 11047: ! 11048: @kindex q (Rmail summary) ! 11049: @findex rmail-summary-quit ! 11050: You can also exit Rmail while in the summary. @kbd{q} (@code{rmail-summary-quit}) ! 11051: kills the summary window, then saves the Rmail file and switches to another ! 11052: buffer. ! 11053: ! 11054: @node Rmail Reply, Rmail Editing, Rmail Summary, Rmail ! 11055: @section Sending Replies ! 11056: ! 11057: Rmail has several commands that use Mail mode to send outgoing mail. ! 11058: @xref{Sending Mail}, for information on using Mail mode. What are ! 11059: documented here are the special commands of Rmail for entering Mail mode. ! 11060: Note that the usual keys for sending mail, @kbd{C-x m} and @kbd{C-x 4 m}, ! 11061: are available in Rmail mode and work just as they usually do.@refill ! 11062: ! 11063: @table @kbd ! 11064: @item m ! 11065: Send a message (@code{rmail-mail}). ! 11066: @item c ! 11067: Continue editing already started outgoing message @*(@code{rmail-continue}). ! 11068: @item r ! 11069: Send a reply to the current Rmail message (@code{rmail-reply}). ! 11070: @item f ! 11071: Forward current message to other users (@code{rmail-forward}). ! 11072: @end table ! 11073: ! 11074: @kindex r (Rmail) ! 11075: @findex rmail-reply ! 11076: @vindex rmail-dont-reply-to ! 11077: @cindex reply to a message ! 11078: The most common reason to send a message while in Rmail is to reply to ! 11079: the message you are reading. To do this, type @kbd{r} ! 11080: (@code{rmail-reply}). This displays the @samp{*mail*} buffer in another ! 11081: window, much like @kbd{C-x 4 m}, but preinitializes the @samp{Subject}, ! 11082: @samp{To}, @samp{CC} and @samp{In-reply-to} header fields based on the ! 11083: message being replied to. The @samp{To} field is given the sender of that ! 11084: message, and the @samp{CC} gets all the recipients of that message (but ! 11085: recipients that match elements of the list @code{rmail-dont-reply-to} are ! 11086: omitted; by default, this list contains your own mailing address).@refill ! 11087: ! 11088: Once you have initialized the @samp{*mail*} buffer this way, sending the ! 11089: mail goes as usual (@pxref{Sending Mail}). You can edit the presupplied ! 11090: header fields if they are not right for you. ! 11091: ! 11092: @kindex C-c C-y (Mail mode) ! 11093: @findex mail-yank-original ! 11094: One additional Mail mode command is available when mailing is invoked ! 11095: from Rmail: @kbd{C-c C-y} (@code{mail-yank-original}) inserts into the outgoing ! 11096: message a copy of the current Rmail message; normally this is the message ! 11097: you are replying to, but you can also switch to the Rmail buffer, select a ! 11098: different message, switch back, and yank new current message. Normally the ! 11099: yanked message is indented four spaces and has most header fields deleted ! 11100: from it; an argument to @kbd{C-c C-y} specifies the amount to indent, and ! 11101: @kbd{C-u C-c C-y} does not indent at all and does not delete any header ! 11102: fields.@refill ! 11103: ! 11104: @kindex f (Rmail) ! 11105: @findex rmail-forward ! 11106: @cindex forward a message ! 11107: Another frequent reason to send mail in Rmail is to forward the current ! 11108: message to other users. @kbd{f} (@code{rmail-forward}) makes this easy by ! 11109: preinitializing the @samp{*mail*} buffer with the current message as the ! 11110: text, and a subject designating a forwarded message. All you have to do is ! 11111: fill in the recipients and send.@refill ! 11112: ! 11113: @kindex m (Rmail) ! 11114: @findex rmail-mail ! 11115: The @kbd{m} (@code{rmail-mail}) command is used to start editing an ! 11116: outgoing message that is not a reply. It leaves the header fields empty. ! 11117: Its only difference from @kbd{C-x 4 m} is that it makes the Rmail buffer ! 11118: accessible for @kbd{C-c y}, just as @kbd{r} does. Thus, @kbd{m} can be ! 11119: used to reply to or forward a message; it can do anything @kbd{r} or @kbd{f} ! 11120: can do.@refill ! 11121: ! 11122: @kindex c (Rmail) ! 11123: @findex rmail-continue ! 11124: The @kbd{c} (@code{rmail-continue}) command resumes editing the ! 11125: @samp{*mail*} buffer, to finish editing an outgoing message you were ! 11126: already composing, or to alter a message you have sent.@refill ! 11127: ! 11128: @node Rmail Editing, Rmail Digest, Rmail Reply, Rmail ! 11129: @section Editing Within a Message ! 11130: ! 11131: Rmail mode provides a few special commands for moving within and editing ! 11132: the current message. In addition, the usual Emacs commands are available ! 11133: (except for a few, such as @kbd{C-M-n} and @kbd{C-M-h}, that are redefined by Rmail for ! 11134: other purposes). However, the Rmail buffer is normally read-only, and to ! 11135: alter it you must use the Rmail command @kbd{w} described below. ! 11136: ! 11137: @table @kbd ! 11138: @item t ! 11139: Toggle display of original headers (@code{rmail-toggle-headers}). ! 11140: @item w ! 11141: Edit current message (@code{rmail-edit-current-message}). ! 11142: @end table ! 11143: ! 11144: @kindex t (Rmail) ! 11145: @findex rmail-toggle-header ! 11146: @vindex rmail-ignored-headers ! 11147: Rmail reformats the header of each message before displaying it. ! 11148: Normally this involves deleting most header fields, on the grounds that ! 11149: they are not interesting. The variable @code{rmail-ignored-headers} should ! 11150: contain a regexp that matches the header fields to discard in this way. ! 11151: The original headers are saved permanently, and to see what they look like, ! 11152: use the @kbd{t} (@code{rmail-toggle-headers}) command. This discards the reformatted ! 11153: headers of the current message and displays it with the original headers. ! 11154: Repeating @kbd{t} reformats the message again. Selecting the message again ! 11155: also reformats. ! 11156: ! 11157: @kindex w (Rmail) ! 11158: @findex rmail-edit-current-message ! 11159: The Rmail buffer is normally read only, and most of the characters you ! 11160: would type to modify it (including most letters) are redefined as Rmail ! 11161: commands. This is usually not a problem since it is rare to want to change ! 11162: the text of a message. When you do want to do this, the way is to type ! 11163: @kbd{w} (@code{rmail-edit-current-message}), which changes from Rmail mode into ! 11164: Rmail Edit mode, another major mode which is nearly the same as Text mode. ! 11165: The mode line illustrates this change. ! 11166: ! 11167: In Rmail Edit mode, letters insert themselves as usual and the Rmail ! 11168: commands are not available. When you are finished editing the message and ! 11169: are ready to go back to Rmail, type @kbd{C-c C-c}, which switches back to ! 11170: Rmail mode. Alternatively, you can return to Rmail mode but cancel all the ! 11171: editing that you have done by typing @kbd{C-c C-]}. ! 11172: ! 11173: @vindex rmail-edit-mode-hook ! 11174: Entering Rmail Edit mode calls with no arguments the value of the variable ! 11175: @code{text-mode-hook}, if that value exists and is not @code{nil}; then it ! 11176: does the same with the variable @code{rmail-edit-mode-hook}. It adds the ! 11177: attribute @samp{edited} to the message. ! 11178: ! 11179: @node Rmail Digest,, Rmail Editing, Rmail ! 11180: @section Digest Messages ! 11181: @cindex digest message ! 11182: @cindex undigestify ! 11183: ! 11184: A @dfn{digest message} is a message which exists to contain and carry ! 11185: several other messages. Digests are used on moderated mailing lists; all ! 11186: the messages that arrive for the list during a period of time such as one ! 11187: day are put inside a single digest which is then sent to the subscribers. ! 11188: Transmitting the single digest uses much less computer time than ! 11189: transmitting the individual messages even though the total size is the ! 11190: same, because the per-message overhead in network mail transmission is ! 11191: considerable. ! 11192: ! 11193: @findex undigestify-rmail-message ! 11194: When you receive a digest message, the most convenient way to read it is ! 11195: to @dfn{undigestify} it: to turn it back into many individual messages. ! 11196: Then you can read and delete the individual messages as it suits you. ! 11197: ! 11198: To undigestify a message, select it and then type @kbd{M-x ! 11199: undigestify-rmail-message}. This copies each submessage as a separate ! 11200: Rmail message and inserts them all following the digest. The digest ! 11201: message itself is flagged as deleted. ! 11202: ! 11203: @iftex ! 11204: @chapter Miscellaneous Commands ! 11205: ! 11206: This chapter contains several brief topics that do not fit anywhere else. ! 11207: ! 11208: @end iftex ! 11209: @node Recursive Edit, Narrowing, Rmail, Top ! 11210: @section Recursive Editing Levels ! 11211: @cindex recursive editing level ! 11212: @cindex editing level, recursive ! 11213: ! 11214: A @dfn{recursive edit} is a situation in which you are using Emacs ! 11215: commands to perform arbitrary editing while in the middle of another Emacs ! 11216: command. For example, when you type @kbd{C-r} inside of a @code{query-replace}, ! 11217: you enter a recursive edit in which you can change the current buffer. On ! 11218: exiting from the recursive edit, you go back to the @code{query-replace}. ! 11219: ! 11220: @kindex C-M-c ! 11221: @findex exit-recursive-edit ! 11222: @cindex exiting ! 11223: @dfn{Exiting} the recursive edit means returning to the unfinished ! 11224: command, which continues execution. For example, exiting the recursive ! 11225: edit requested by @kbd{C-r} in @code{query-replace} causes query replacing ! 11226: to resume. Exiting is done with @kbd{C-M-c} (@code{exit-recursive-edit}). ! 11227: ! 11228: @kindex C-] ! 11229: @findex abort-recursive-edit ! 11230: You can also @dfn{abort} the recursive edit. This is like exiting, but ! 11231: also quits the unfinished command immediately. Use the command @kbd{C-]} ! 11232: (@code{abort-recursive-edit}) for this. @xref{Quitting}. ! 11233: ! 11234: The mode line shows you when you are in a recursive edit by displaying ! 11235: square brackets around the parentheses that always surround the major and ! 11236: minor mode names. Every window's mode line shows this, in the same way, ! 11237: since being in a recursive edit is true of Emacs as a whole rather than ! 11238: any particular buffer. ! 11239: ! 11240: @findex top-level ! 11241: It is possible to be in recursive edits within recursive edits. For ! 11242: example, after typing @kbd{C-r} in a @code{query-replace}, you might type a ! 11243: command that entered the debugger. In such circumstances, two or more sets ! 11244: of square brackets appear in the mode line. Exiting the inner recursive ! 11245: edit (such as, with the debugger @kbd{c} command) would resume the command ! 11246: where it called the debugger. After the end of this command, you would be ! 11247: able to exit the first recursive edit. Aborting also gets out of only one ! 11248: level of recursive edit; it returns immediately to the command level of the ! 11249: previous recursive edit. So you could immediately abort that one too. ! 11250: ! 11251: Alternatively, the command @kbd{M-x top-level} aborts all levels of ! 11252: recursive edits, returning immediately to the top level command reader. ! 11253: ! 11254: The text being edited inside the recursive edit need not be the same text ! 11255: that you were editing at top level. It depends on what the recursive edit ! 11256: is for. If the command that invokes the recursive edit selects a different ! 11257: buffer first, that is the buffer you will edit recursively. In any case, ! 11258: you can switch buffers within the recursive edit in the normal manner (as ! 11259: long as the buffer-switching keys have not been rebound). You could ! 11260: probably do all the rest of your editing inside the recursive edit, ! 11261: visiting files and all. But this could have surprising effects (such as ! 11262: stack overflow) from time to time. So remember to exit or abort the ! 11263: recursive edit when you no longer need it. ! 11264: ! 11265: In general, GNU Emacs tries to avoid using recursive edits. It is ! 11266: usually preferable to allow the user to switch among the possible editing ! 11267: modes in any order he likes. With recursive edits, the only way to get to ! 11268: another state is to go ``back'' to the state that the recursive edit was ! 11269: invoked from. ! 11270: ! 11271: @node Narrowing, Sorting, Recursive Edit, Top ! 11272: @section Narrowing ! 11273: @cindex widening ! 11274: @cindex restriction ! 11275: @cindex narrowing ! 11276: ! 11277: @dfn{Narrowing} means focusing in on some portion of the buffer, making ! 11278: the rest temporarily invisible and inaccessible. Cancelling the narrowing, ! 11279: and making the entire buffer once again visible, is called @dfn{widening}. ! 11280: The amount of narrowing in effect in a buffer at any time is called the ! 11281: buffer's @dfn{restriction}. ! 11282: ! 11283: @c WideCommands ! 11284: @table @kbd ! 11285: @item C-x n ! 11286: Narrow down to between point and mark (@code{narrow-to-region}). ! 11287: @item C-x w ! 11288: Widen to make the entire buffer visible again (@code{widen}). ! 11289: @end table ! 11290: ! 11291: When you have narrowed down to a part of the buffer, that part appears to ! 11292: be all there is. You can't see the rest, you can't move into it (motion ! 11293: commands won't go outside the visible part), you can't change it in any ! 11294: way. However, it is not gone, and if you save the file all the invisible ! 11295: text will be saved. In addition to sometimes making it easier to ! 11296: concentrate on a single subroutine or paragraph by eliminating clutter, ! 11297: narrowing can be used to restrict the range of operation of a replace ! 11298: command or repeating keyboard macro. The word @samp{Narrow} appears in the ! 11299: mode line whenever narrowing is in effect. ! 11300: ! 11301: @kindex C-x n ! 11302: @findex narrow-to-region ! 11303: The primary narrowing command is @kbd{C-x n} (@code{narrow-to-region}). ! 11304: It sets the current buffer's restrictions so that the text in the current ! 11305: region remains visible but all text before the region or after the region ! 11306: is invisible. Point and mark do not change. ! 11307: ! 11308: Because narrowing can easily confuse users who do not understand it, ! 11309: @code{narrow-to-region} is normally a disabled command. Attempting to use ! 11310: this command asks for confirmation and gives you the option of enabling it; ! 11311: once you enable the command, confirmation will no longer be required for ! 11312: it. @xref{Disabling}. ! 11313: ! 11314: @kindex C-x w ! 11315: @findex widen ! 11316: The way to undo narrowing is to widen with @kbd{C-x w} (@code{widen}). ! 11317: This makes all text in the buffer accessible again. ! 11318: ! 11319: You can get information on what part of the buffer you are narrowed down ! 11320: to using the @kbd{C-x =} command. @xref{Position Info}. ! 11321: ! 11322: @node Sorting, Shell, Narrowing, Top ! 11323: @section Sorting Text ! 11324: @cindex sorting ! 11325: ! 11326: Emacs provides several commands for sorting text in the buffer. All ! 11327: operate on the contents of the region (the text between point and the ! 11328: mark). They divide the text of the region into many @dfn{sort records}, ! 11329: identify a @dfn{sort key} for each record, and then reorder the records ! 11330: into the order determined by the sort keys. The records are ordered so ! 11331: that their keys are in alphabetical order, or, for numeric sorting, in ! 11332: numeric order. In alphabetic sorting, all upper case letters `A' through ! 11333: `Z' come before lower case `a', in accord with the ASCII character ! 11334: sequence. ! 11335: ! 11336: The various sort commands differ in how they divide the text into sort ! 11337: records and in which part of each record is used as the sort key. Most of ! 11338: the commands make each line a separate sort record, but some commands use ! 11339: paragraphs or pages as sort records. Most of the sort commands use each ! 11340: entire sort record as its own sort key, but some use only a portion of the ! 11341: record as the sort key. ! 11342: ! 11343: @findex sort-lines ! 11344: @findex sort-paragraphs ! 11345: @findex sort-pages ! 11346: @findex sort-fields ! 11347: @findex sort-numeric-fields ! 11348: @table @kbd ! 11349: @item M-x sort-lines ! 11350: Divide the region into lines, and sort by comparing the entire ! 11351: text of a line. A prefix argument means sort into descending order. ! 11352: ! 11353: @item M-x sort-paragraphs ! 11354: Divide the region into paragraphs, and sort by comparing the entire ! 11355: text of a paragraph (except for leading blank lines). A prefix ! 11356: argument means sort into descending order. ! 11357: ! 11358: @item M-x sort-pages ! 11359: Divide the region into pages, and sort by comparing the entire ! 11360: text of a page (except for leading blank lines). A prefix ! 11361: argument means sort into descending order. ! 11362: ! 11363: @item M-x sort-fields ! 11364: Divide the region into lines, and sort by comparing the contents of ! 11365: one field in each line. Fields are defined as separated by ! 11366: whitespace, so the first run of consecutive non-whitespace characters ! 11367: in a line constitutes field 1, the second such run constitutes field ! 11368: 2, etc. ! 11369: ! 11370: You specify which field to sort by with a numeric argument: 1 to sort ! 11371: by field 1, etc. A negative argument means sort into descending ! 11372: order. Thus, minus 2 means sort by field 2 in reverse-alphabetical ! 11373: order. ! 11374: ! 11375: @item M-x sort-numeric-fields ! 11376: Like @kbd{M-x sort-fields} except the specified field is converted ! 11377: to a number for each line, and the numbers are compared. @samp{10} ! 11378: comes before @samp{2} when considered as text, but after it when ! 11379: considered as a number. ! 11380: ! 11381: @item M-x sort-columns ! 11382: Like @kbd{M-x sort-fields} except that the text within each line ! 11383: used for comparison comes from a fixed range of columns. See below ! 11384: for an explanation. ! 11385: @end table ! 11386: ! 11387: For example, if the buffer contains ! 11388: ! 11389: @smallexample ! 11390: On systems where clash detection (locking of files being edited) is ! 11391: implemented, Emacs also checks the first time you modify a buffer ! 11392: whether the file has changed on disk since it was last visited or ! 11393: saved. If it has, you are asked to confirm that you want to change ! 11394: the buffer. ! 11395: @end smallexample ! 11396: ! 11397: @noindent ! 11398: then if you apply @kbd{M-x sort-lines} to the entire buffer you get ! 11399: ! 11400: @smallexample ! 11401: On systems where clash detection (locking of files being edited) is ! 11402: implemented, Emacs also checks the first time you modify a buffer ! 11403: saved. If it has, you are asked to confirm that you want to change ! 11404: the buffer. ! 11405: whether the file has changed on disk since it was last visited or ! 11406: @end smallexample ! 11407: ! 11408: @noindent ! 11409: where the upper case `O' comes before all lower case letters. If you apply ! 11410: instead @kbd{C-u 2 M-x sort-fields} you get ! 11411: ! 11412: @smallexample ! 11413: implemented, Emacs also checks the first time you modify a buffer ! 11414: saved. If it has, you are asked to confirm that you want to change ! 11415: the buffer. ! 11416: On systems where clash detection (locking of files being edited) is ! 11417: whether the file has changed on disk since it was last visited or ! 11418: @end smallexample ! 11419: ! 11420: @noindent ! 11421: where the sort keys were @samp{Emacs}, @samp{If}, @samp{buffer}, ! 11422: @samp{systems} and @samp{the}.@refill ! 11423: ! 11424: @findex sort-columns ! 11425: @kbd{M-x sort-columns} requires more explanation. You specify the ! 11426: columns by putting point at one of the columns and the mark at the other ! 11427: column. Because this means you cannot put point or the mark at the ! 11428: beginning of the first line to sort, this command uses an unusual ! 11429: definition of `region': all of the line point is in is considered part of ! 11430: the region, and so is all of the line the mark is in. ! 11431: ! 11432: For example, to sort a table by information found in columns 10 to 15, ! 11433: you could put the mark on column 10 in the first line of the table, and ! 11434: point on column 15 in the last line of the table, and then use this command. ! 11435: Or you could put the mark on column 15 in the first line and point on ! 11436: column 10 in the last line. ! 11437: ! 11438: This can be thought of as sorting the rectangle specified by point and ! 11439: the mark, except that the text on each line to the left or right of the ! 11440: rectangle moves along with the text inside the rectangle. ! 11441: @xref{Rectangles}. ! 11442: ! 11443: @node Shell, Hardcopy, Sorting, Top ! 11444: @section Running Shell Commands from Emacs ! 11445: @cindex subshell ! 11446: @cindex shell commands ! 11447: ! 11448: Emacs has commands for passing single command lines to inferior shell ! 11449: processes; it can also run a shell interactively with input and output to ! 11450: an Emacs buffer @samp{*shell*}. ! 11451: ! 11452: @table @kbd ! 11453: @item M-! ! 11454: Run a specified shell command line and display the output ! 11455: (@code{shell-command}). ! 11456: @item M-| ! 11457: Run a specified shell command line with region contents as input; ! 11458: optionally replace the region with the output ! 11459: (@code{shell-command-on-region}). ! 11460: @item M-x shell ! 11461: Run a subshell with input and output through an Emacs buffer. ! 11462: You can then give commands interactively. ! 11463: @end table ! 11464: ! 11465: @menu ! 11466: * Single Shell:: How to run one shell command and return. ! 11467: * Interactive Shell:: Permanent shell taking input via Emacs. ! 11468: * Shell Mode:: Special Emacs commands used with permanent shell. ! 11469: @end menu ! 11470: ! 11471: @node Single Shell, Interactive Shell, Shell, Shell ! 11472: @subsection Single Shell Commands ! 11473: ! 11474: @kindex M-! ! 11475: @findex shell-command ! 11476: @kbd{M-!} (@code{shell-command}) reads a line of text using the ! 11477: minibuffer and creates an inferior shell to execute the line as a command. ! 11478: Standard input from the command comes from the null device. If the shell ! 11479: command produces any output, the output goes into an Emacs buffer named ! 11480: @samp{*Shell Command Output*}, which is displayed in another window but not ! 11481: selected. A numeric argument, as in @kbd{M-1 M-!}, directs this command to ! 11482: insert any output into the current buffer. In that case, point is left ! 11483: before the output and the mark is set after the output. ! 11484: ! 11485: @kindex M-| ! 11486: @findex shell-command-on-region ! 11487: @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!} but passes ! 11488: the contents of the region as input to the shell command, instead of no ! 11489: input. If a numeric argument is used, meaning insert output in the current ! 11490: buffer, then the old region is deleted first and the output replaces it as ! 11491: the contents of the region.@refill ! 11492: ! 11493: @vindex shell-file-name ! 11494: @cindex environment ! 11495: Both @kbd{M-!} and @kbd{M-|} use @code{shell-file-name} to specify the ! 11496: shell to use. This variable is initialized based on your @code{SHELL} ! 11497: environment variable when Emacs is started. If the file name does not ! 11498: specify a directory, the directories in the list @code{exec-path} are ! 11499: searched; this list is initialized based on the environment variable ! 11500: @code{PATH} when Emacs is started. Your @file{.emacs} file can override ! 11501: either or both of these default initializations.@refill ! 11502: ! 11503: With @kbd{M-!} and @kbd{M-|}, Emacs has to wait until the shell command ! 11504: completes. You can quit with @kbd{C-g}; that terminates the shell command. ! 11505: ! 11506: @node Interactive Shell, Shell Mode, Single Shell, Shell ! 11507: @subsection Interactive Inferior Shell ! 11508: ! 11509: @findex shell ! 11510: To run a subshell interactively, putting its typescript in an Emacs ! 11511: buffer, use @kbd{M-x shell}. This creates (or reuses) a buffer named ! 11512: @samp{*shell*} and runs a subshell with input coming from and output going ! 11513: to that buffer. That is to say, any ``terminal output'' from the subshell ! 11514: will go into the buffer, advancing point, and any ``terminal input'' for ! 11515: the subshell comes from text in the buffer. To give input to the subshell, ! 11516: go to the end of the buffer and type the input, terminated by @key{RET}. ! 11517: ! 11518: Emacs does not wait for the subshell to do anything. You can switch ! 11519: windows or buffers and edit them while the shell is waiting, or while it is ! 11520: running a command. Output from the subshell waits until Emacs has time to ! 11521: process it; this happens whenever Emacs is waiting for keyboard input or ! 11522: for time to elapse. ! 11523: ! 11524: If you would like multiple subshells, change the name of buffer ! 11525: @samp{*shell*} to something different by using @kbd{M-x rename-buffer}. The ! 11526: next use of @kbd{M-x shell} will create a new buffer @samp{*shell*} with ! 11527: its own subshell. By renaming this buffer as well you can create a third ! 11528: one, and so on. All the subshells run independently and in parallel. ! 11529: ! 11530: @vindex explicit-shell-file-name ! 11531: The file name used to load the subshell is the value of the variable ! 11532: @code{explicit-shell-file-name}, if that is non-@code{nil}. Otherwise, the ! 11533: environment variable @code{ESHELL} is used, or the environment variable ! 11534: @code{SHELL} if there is no @code{ESHELL}. If the file name specified ! 11535: is relative, the directories in the list @code{exec-path} are searched ! 11536: (@pxref{Single Shell,Single Shell Commands}).@refill ! 11537: ! 11538: As soon as the subshell is started, it is sent as input the contents of ! 11539: the file @file{~/.emacs_@var{shellname}}, if that file exists, where ! 11540: @var{shellname} is the name of the file that the shell was loaded from. ! 11541: For example, if you use @code{csh}, the file sent to it is ! 11542: @file{~/.emacs_csh}.@refill ! 11543: ! 11544: @vindex shell-pushd-regexp ! 11545: @vindex shell-popd-regexp ! 11546: @vindex shell-cd-regexp ! 11547: @code{cd}, @code{pushd} and @code{popd} commands given to the inferior ! 11548: shell are watched by Emacs so it can keep the @samp{*shell*} buffer's ! 11549: default directory the same as the shell's working directory. These ! 11550: commands are recognized syntactically by examining lines of input that are ! 11551: sent. If you use aliases for these commands, you can tell Emacs to ! 11552: recognize them also. For example, if the value of the variable ! 11553: @code{shell-pushd-regexp} matches the beginning of a shell command line, ! 11554: that line is regarded as a @code{pushd} command. Change this variable when ! 11555: you add aliases for @samp{pushd}. Likewise, @code{shell-popd-regexp} and ! 11556: @code{shell-cd-regexp} are used to recognize commands with the meaning of ! 11557: @samp{popd} and @samp{cd}. These commands are recognized only at the ! 11558: beginning of a shell command line.@refill ! 11559: ! 11560: @vindex shell-set-directory-error-hook ! 11561: If Emacs gets an error while trying to handle what it believes is ! 11562: a @samp{cd}, @samp{pushd} or @samp{popd} command, and the value of ! 11563: @code{shell-set-directory-error-hook} is non-@code{nil}, that value is ! 11564: called as a function with no arguments.@refill ! 11565: ! 11566: @node Shell Mode,, Interactive Shell, Shell ! 11567: @subsection Shell Mode ! 11568: ! 11569: @cindex Shell mode ! 11570: The shell buffer uses Shell mode, which defines several special keys ! 11571: attached to the @kbd{C-c} prefix. They are chosen to resemble the usual ! 11572: editing and job control characters present in shells that are not under ! 11573: Emacs, except that you must type @kbd{C-c} first. Here is a complete list ! 11574: of the special key bindings of Shell mode: ! 11575: ! 11576: @kindex RET (Shell mode) ! 11577: @kindex C-c C-d (Shell mode) ! 11578: @kindex C-c C-u (Shell mode) ! 11579: @kindex C-c C-w (Shell mode) ! 11580: @kindex C-c C-c (Shell mode) ! 11581: @kindex C-c C-z (Shell mode) ! 11582: @kindex C-c C-\ (Shell mode) ! 11583: @kindex C-c C-o (Shell mode) ! 11584: @kindex C-c C-r (Shell mode) ! 11585: @kindex C-c C-y (Shell mode) ! 11586: @findex send-shell-input ! 11587: @findex shell-send-eof ! 11588: @findex interrupt-shell-subjob ! 11589: @findex stop-shell-subjob ! 11590: @findex quit-shell-subjob ! 11591: @findex kill-output-from-shell ! 11592: @findex show-output-from-shell ! 11593: @findex copy-last-shell-input ! 11594: @vindex shell-prompt-pattern ! 11595: @table @kbd ! 11596: @item @key{RET} ! 11597: At end of buffer send line as input; otherwise, copy current line to end of ! 11598: buffer and send it (@code{send-shell-input}). When a line is copied, any ! 11599: text at the beginning of the line that matches the variable ! 11600: @code{shell-prompt-pattern} is left out; this variable's value should be a ! 11601: regexp string that matches the prompts that you use in your subshell. ! 11602: @item C-c C-d ! 11603: Send end-of-file as input, probably causing the shell or its current ! 11604: subjob to finish (@code{shell-send-eof}). ! 11605: @item C-c C-u ! 11606: Kill all text that has yet to be sent as input (@code{kill-shell-input}). ! 11607: @item C-c C-w ! 11608: Kill a word before point (@code{backward-kill-word}). ! 11609: @item C-c C-c ! 11610: Interrupt the shell or its current subjob if any ! 11611: (@code{interrupt-shell-subjob}). ! 11612: @item C-c C-z ! 11613: Stop the shell or its current subjob if any (@code{stop-shell-subjob}). ! 11614: @item C-c C-\ ! 11615: Send quit signal to the shell or its current subjob if any ! 11616: (@code{quit-shell-subjob}). ! 11617: @item C-c C-o ! 11618: Delete last batch of output from shell (@code{kill-output-from-shell}). ! 11619: @item C-c C-r ! 11620: Scroll top of last batch of output to top of window ! 11621: (@code{show-output-from-shell}). ! 11622: @item C-c C-y ! 11623: Copy the previous bunch of shell input, and insert it into the ! 11624: buffer before point (@code{copy-last-shell-input}). No final newline ! 11625: is inserted, and the input copied is not resubmitted until you type ! 11626: @key{RET}. ! 11627: @end table ! 11628: ! 11629: @node Hardcopy, Dissociated Press, Shell, Top ! 11630: @section Hardcopy Output ! 11631: @cindex hardcopy ! 11632: ! 11633: The Emacs commands for making hardcopy derive their names from the ! 11634: Unix commands @samp{print} and @samp{lpr}. ! 11635: ! 11636: @table @kbd ! 11637: @item M-x print-buffer ! 11638: Print hardcopy of current buffer using Unix command @samp{print} ! 11639: (@samp{lpr -p}). This makes page headings containing the file name ! 11640: and page number. ! 11641: @item M-x lpr-buffer ! 11642: Print hardcopy of current buffer using Unix command @samp{lpr}. ! 11643: This makes no page headings. ! 11644: @item M-x print-region ! 11645: Like @code{print-buffer} but prints only the current region. ! 11646: @item M-x lpr-region ! 11647: Like @code{lpr-buffer} but prints only the current region. ! 11648: @end table ! 11649: ! 11650: @findex print-buffer ! 11651: @findex print-region ! 11652: @findex lpr-buffer ! 11653: @findex lpr-region ! 11654: @vindex lpr-switches ! 11655: All the hardcopy commands pass extra switches to the @code{lpr} program ! 11656: based on the value of the variable @code{lpr-switches}. Its value should ! 11657: be a list of strings, each string a switch starting with @samp{-}. For ! 11658: example, the value could be @code{("-Pfoo")} to print on printer ! 11659: @samp{foo}. ! 11660: ! 11661: @node Dissociated Press, Amusements, Hardcopy, Top ! 11662: @section Dissociated Press ! 11663: ! 11664: @findex dissociated-press ! 11665: @kbd{M-x dissociated-press} is a command for scrambling a file of text ! 11666: either word by word or character by character. Starting from a buffer of ! 11667: straight English, it produces extremely amusing output. The input comes ! 11668: from the current Emacs buffer. Dissociated Press writes its output in a ! 11669: buffer named @samp{*Dissociation*}, and redisplays that buffer after every ! 11670: couple of lines (approximately) to facilitate reading it. ! 11671: ! 11672: @code{dissociated-press} asks every so often whether to continue ! 11673: operating. Answer @kbd{n} to stop it. You can also stop at any time by ! 11674: typing @kbd{C-g}. The dissociation output remains in the @samp{*Dissociation*} ! 11675: buffer for you to copy elsewhere if you wish. ! 11676: ! 11677: @cindex presidentagon ! 11678: Dissociated Press operates by jumping at random from one point in the ! 11679: buffer to another. In order to produce plausible output rather than ! 11680: gibberish, it insists on a certain amount of overlap between the end of one ! 11681: run of consecutive words or characters and the start of the next. That is, ! 11682: if it has just printed out `president' and then decides to jump to a ! 11683: different point in the file, it might spot the `ent' in `pentagon' and ! 11684: continue from there, producing `presidentagon'. Long sample texts produce ! 11685: the best results. ! 11686: ! 11687: @cindex againformation ! 11688: A positive argument to @kbd{M-x dissociated-press} tells it to operate ! 11689: character by character, and specifies the number of overlap characters. A ! 11690: negative argument tells it to operate word by word and specifies the number ! 11691: of overlap words. In this mode, whole words are treated as the elements to ! 11692: be permuted, rather than characters. No argument is equivalent to an ! 11693: argument of two. For your againformation, the output goes only into the ! 11694: buffer @samp{*Dissociation*}. The buffer you start with is not changed. ! 11695: ! 11696: @cindex Markov chain ! 11697: @cindex ignoriginal ! 11698: @cindex techniquitous ! 11699: Dissociated Press produces nearly the same results as a Markov chain ! 11700: based on a frequency table constructed from the sample text. It is, ! 11701: however, an independent, ignoriginal invention. Dissociated Press ! 11702: techniquitously copies several consecutive characters from the sample ! 11703: between random choices, whereas a Markov chain would choose randomly for ! 11704: each word or character. This makes for more plausible sounding results, ! 11705: and runs faster. ! 11706: ! 11707: @cindex outragedy ! 11708: @cindex buggestion ! 11709: @cindex properbose ! 11710: It is a mustatement that too much use of Dissociated Press can be a ! 11711: developediment to your real work. Sometimes to the point of outragedy. ! 11712: And keep dissociwords out of your documentation, if you want it to be well ! 11713: userenced and properbose. Have fun. Your buggestions are welcome. ! 11714: ! 11715: @node Amusements, Emulation, Dissociated Press, Top ! 11716: @section Other Amusements ! 11717: @cindex boredom ! 11718: @findex hanoi ! 11719: @findex yow ! 11720: ! 11721: If you are a little bit bored, you can try @kbd{M-x hanoi}. If you are ! 11722: considerably bored, give it a numeric argument. If you are very very ! 11723: bored, try an argument of 9. Sit back and watch. ! 11724: ! 11725: When you are frustrated, try the famous Eliza program. Just do ! 11726: @kbd{M-x doctor}. End each input by typing @kbd{RET} twice. ! 11727: ! 11728: When you are feeling strange, type @kbd{M-x yow}. ! 11729: ! 11730: @node Emulation, Customization, Amusements, Top ! 11731: @section Emulation ! 11732: @cindex other editors ! 11733: @cindex EDT ! 11734: @cindex vi ! 11735: ! 11736: GNU Emacs can be programmed to emulate (more or less) most other ! 11737: editors. Standard facilities can emulate these: ! 11738: ! 11739: @table @asis ! 11740: @item EDT (DEC VMS editor) ! 11741: @findex edt-emulation-on ! 11742: @findex edt-emulation-off ! 11743: Turn on EDT emulation with @kbd{M-x edt-emulation-on}. @kbd{M-x ! 11744: edt-emulation-off} restores normal Emacs command bindings. ! 11745: ! 11746: Most of the EDT emulation commands are keypad keys, and most standard ! 11747: Emacs key bindings are still available. The EDT emulation rebindings ! 11748: are done in the global keymap, so there is no problem switching ! 11749: buffers or major modes while in EDT emulation. ! 11750: ! 11751: @item Gosling Emacs ! 11752: @findex set-gosmacs-bindings ! 11753: @findex set-gnu-bindings ! 11754: Turn on emulation of Gosling Emacs (aka Unipress Emacs) with @kbd{M-x ! 11755: set-gosmacs-bindings}. This redefines many keys, mostly on the ! 11756: @kbd{C-x} and @kbd{ESC} prefixes, to work as they do in Gosmacs. ! 11757: @kbd{M-x set-gnu-bindings} returns to normal GNU Emacs by rebinding ! 11758: the same keys to the definitions they had at the time @kbd{M-x ! 11759: set-gosmacs-bindings} was done. ! 11760: ! 11761: It is also possible to run Mocklisp code written for Gosling Emacs. ! 11762: @xref{Mocklisp}. ! 11763: ! 11764: @item vi (Berkeley Unix editor) ! 11765: @findex vi-mode ! 11766: Turn on vi emulation with @kbd{M-x vi-mode}. This is a major mode ! 11767: that replaces the previously established major mode. All of the ! 11768: vi commands that, in real vi, enter ``input'' mode are programmed ! 11769: in the Emacs emulator to return to the previous major mode. Thus, ! 11770: ordinary Emacs serves as vi's ``input'' mode. ! 11771: ! 11772: Because vi emulation works through major modes, it does not work ! 11773: to switch buffers during emulation. Return to normal Emacs first. ! 11774: ! 11775: If you plan to use vi emulation much, you probably want to bind a key ! 11776: to the @code{vi-mode} command. ! 11777: ! 11778: @item vi (alternate emulator) ! 11779: @findex vip-mode ! 11780: Another vi emulator said to resemble real vi more thoroughly is ! 11781: invoked by @kbd{M-x vip-mode}. ``Input'' mode in this emulator is ! 11782: changed from ordinary Emacs so you can use @key{ESC} to go back to ! 11783: emulated vi command mode. To get from emulated vi command mode back ! 11784: to ordinary Emacs, type @kbd{C-z}. ! 11785: ! 11786: This emulation does not work through major modes, and it is possible ! 11787: to switch buffers in various ways within the emulator. It is not ! 11788: so necessary to assign a key to the command @code{vip-mode} as ! 11789: it is with @code{vi-mode} because terminating insert mode does ! 11790: not use it. ! 11791: ! 11792: For full information, see the long comment at the beginning of the ! 11793: source file, which is @file{lisp/vip.el} in the Emacs distribution. ! 11794: @end table ! 11795: ! 11796: I am interested in hearing which vi emulator users prefer, as well as in ! 11797: receiving more complete user documentation for either or both emulators. ! 11798: Warning: loading both at once may cause name conficts; no one has checked. ! 11799: ! 11800: @node Customization, Quitting, Emulation, Top ! 11801: @chapter Customization ! 11802: @cindex customization ! 11803: ! 11804: This chapter talks about various topics relevant to adapting the ! 11805: behavior of Emacs in minor ways. ! 11806: ! 11807: All kinds of customization affect only the particular Emacs job that you ! 11808: do them in. They are completely lost when you kill the Emacs job, and have ! 11809: no effect on other Emacs jobs you may run at the same time or later. The ! 11810: only way an Emacs job can affect anything outside of it is by writing a ! 11811: file; in particular, the only way to make a customization `permanent' is to ! 11812: put something in your @file{.emacs} file or other appropriate file to do the ! 11813: customization in each session. @xref{Init File}. ! 11814: ! 11815: @menu ! 11816: * Minor Modes:: Each minor mode is one feature you can turn on ! 11817: independently of any others. ! 11818: * Variables:: Many Emacs commands examine Emacs variables ! 11819: to decide what to do; by setting variables, ! 11820: you can control their functioning. ! 11821: * Keyboard Macros:: A keyboard macro records a sequence of keystrokes ! 11822: to be replayed with a single command. ! 11823: * Key Bindings:: The keymaps say what command each key runs. ! 11824: By changing them, you can "redefine keys". ! 11825: * Syntax:: The syntax table controls how words and expressions ! 11826: are parsed. ! 11827: * Init File:: How to write common customizations in the @file{.emacs} file. ! 11828: @end menu ! 11829: ! 11830: @node Minor Modes, Variables, Customization, Customization ! 11831: @section Minor Modes ! 11832: @cindex minor modes ! 11833: ! 11834: @cindex mode line ! 11835: Minor modes are options which you can use or not. For example, Auto Fill ! 11836: mode is a minor mode in which @key{SPC} breaks lines between words as you ! 11837: type. All the minor modes are independent of each other and of the ! 11838: selected major mode. Most minor modes say in the mode line when they are ! 11839: on; for example, @samp{Fill} in the mode line means that Auto Fill mode is ! 11840: on. ! 11841: ! 11842: Append @code{-mode} to the name of a minor mode to get the name of a ! 11843: command function that turns the mode on or off. Thus, the command to ! 11844: enable or disable Auto Fill mode is called @kbd{M-x auto-fill-mode}. These ! 11845: commands are usually invoked with @kbd{M-x}, but you can bind keys to them ! 11846: if you wish. With no argument, the function turns the mode on if it was ! 11847: off and off if it was on. This is known as @dfn{toggling}. A positive ! 11848: argument always turns the mode on, and an explicit zero argument or a ! 11849: negative argument always turns it off. ! 11850: ! 11851: @cindex Auto Fill mode ! 11852: @findex auto-fill-mode ! 11853: Auto Fill mode allows you to enter filled text without breaking lines ! 11854: explicitly. Emacs inserts newlines as necessary to prevent lines from ! 11855: becoming too long. @xref{Filling}. ! 11856: ! 11857: @cindex Overwrite mode ! 11858: @findex overwrite-mode ! 11859: Overwrite mode causes ordinary printing characters to replace existing ! 11860: text instead of shoving it over. For example, if the point is in front of ! 11861: the @samp{B} in @samp{FOOBAR}, then in Overwrite mode typing a @kbd{G} ! 11862: changes it to @samp{FOOGAR}, instead of making it @samp{FOOGBAR} as ! 11863: usual.@refill ! 11864: ! 11865: @cindex Abbrev mode ! 11866: @findex abbrev-mode ! 11867: Abbrev mode allows you to define abbreviations that automatically expand ! 11868: as you type them. For example, @samp{amd} might expand to @samp{abbrev ! 11869: mode}. @xref{Abbrevs}, for full information. ! 11870: ! 11871: @node Variables, Keyboard Macros, Minor Modes, Customization ! 11872: @section Variables ! 11873: @cindex variable ! 11874: @cindex option ! 11875: ! 11876: A @dfn{variable} is a Lisp symbol which has a value. The symbol's name ! 11877: is also called the name of the variable. Variable names can contain any ! 11878: characters, but conventionally they are chosen to be words separated by ! 11879: hyphens. A variable can have a documentation string which describes what ! 11880: kind of value it should have and how the value will be used. ! 11881: ! 11882: Lisp allows any variable to have any kind of value, but most variables ! 11883: that Emacs uses require a value of a certain type. Often the value should ! 11884: always be a string, or should always be a number. Sometimes we say that a ! 11885: certain feature is turned on if a variable is ``non-@code{nil},'' meaning ! 11886: that if the variable's value is @code{nil}, the feature is off, but the ! 11887: feature is on for @i{any} other value. The conventional value to use to ! 11888: turn on the feature---since you have to pick one particular value when you ! 11889: set the variable---is @code{t}. ! 11890: ! 11891: Emacs uses many Lisp variables for internal recordkeeping, as any Lisp ! 11892: program must, but the most interesting variables for you are the ones that ! 11893: exist for the sake of customization. Emacs does not (usually) change the ! 11894: values of these variables; instead, you set the values, and thereby alter ! 11895: and control the behavior of certain Emacs commands. These variables are ! 11896: called @dfn{options}. Most options are documented in this manual, and ! 11897: appear in the Variable Index (@pxref{Variable Index}). ! 11898: ! 11899: One example of a variable which is an option is @code{fill-column}, which ! 11900: specifies the position of the right margin (as a number of characters from ! 11901: the left margin) to be used by the fill commands (@pxref{Filling}). ! 11902: ! 11903: @menu ! 11904: * Examining:: Examining or setting one variable's value. ! 11905: * Edit Options:: Examining or editing list of all variables' values. ! 11906: * Locals:: Per-buffer values of variables. ! 11907: * File Variables:: How files can specify variable values. ! 11908: @end menu ! 11909: ! 11910: @node Examining, Edit Options, Variables, Variables ! 11911: @subsection Examining and Setting Variables ! 11912: @cindex setting variables ! 11913: ! 11914: @table @kbd ! 11915: @item C-h v ! 11916: @itemx M-x describe-variable ! 11917: Print the value and documentation of a variable. ! 11918: @item M-x set-variable ! 11919: Change the value of a variable. ! 11920: @end table ! 11921: ! 11922: @kindex C-h v ! 11923: @findex describe-variable ! 11924: To examine the value of a single variable, use @kbd{C-h v} ! 11925: (@code{describe-variable}), which reads a variable name using the ! 11926: minibuffer, with completion. It prints both the value and the ! 11927: documentation of the variable. ! 11928: ! 11929: @example ! 11930: C-h v fill-column @key{RET} ! 11931: @end example ! 11932: @noindent ! 11933: prints something like ! 11934: @smallexample ! 11935: fill-column's value is 75 ! 11936: ! 11937: Documentation: ! 11938: *Column beyond which automatic line-wrapping should happen. ! 11939: Automatically becomes local when set in any fashion. ! 11940: @end smallexample ! 11941: ! 11942: @cindex option ! 11943: @noindent ! 11944: The star at the beginning of the documentation indicates that this variable ! 11945: is an option. @kbd{C-h v} is not restricted to options; it allows any ! 11946: variable name. ! 11947: ! 11948: @findex set-variable ! 11949: If you know which option you want to set, you can set it using @kbd{M-x ! 11950: set-variable}. This reads the variable name with the minibuffer (with ! 11951: completion), and then reads a Lisp expression for the new value using the ! 11952: minibuffer a second time. For example, ! 11953: ! 11954: @example ! 11955: M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET} ! 11956: @end example ! 11957: ! 11958: @noindent ! 11959: sets @code{fill-column} to 75, like executing the Lisp expression ! 11960: ! 11961: @example ! 11962: (setq fill-column 75) ! 11963: @end example ! 11964: ! 11965: Setting variables in this way, like all means of customizing Emacs ! 11966: except where explicitly stated, affects only the current Emacs session. ! 11967: ! 11968: @node Edit Options, Locals, Examining, Variables ! 11969: @subsection Editing Variable Values ! 11970: ! 11971: @table @kbd ! 11972: @item M-x list-options ! 11973: Display a buffer listing names, values and documentation of all options. ! 11974: @item M-x edit-options ! 11975: Change option values by editing a list of options. ! 11976: @end table ! 11977: ! 11978: @findex list-options ! 11979: @kbd{M-x list-options} displays a list of all Emacs option variables, in ! 11980: an Emacs buffer named @samp{*List Options*}. Each option is shown with its ! 11981: documentation and its current value. Here is what a portion of it might ! 11982: look like: ! 11983: ! 11984: @smallexample ! 11985: ;; exec-path: ! 11986: ("." "/usr/local/bin" "/usr/ucb" "/bin" "/usr/bin" "/u2/emacs/etc") ! 11987: *List of directories to search programs to run in subprocesses. ! 11988: Each element is a string (directory name) ! 11989: or nil (try the default directory). ! 11990: ;; ! 11991: ;; fill-column: ! 11992: 75 ! 11993: *Column beyond which automatic line-wrapping should happen. ! 11994: Automatically becomes local when set in any fashion. ! 11995: ;; ! 11996: @end smallexample ! 11997: ! 11998: @findex edit-options ! 11999: @kbd{M-x edit-options} goes one step further and immediately selects the ! 12000: @samp{*List Options*} buffer; this buffer uses the major mode Options mode, ! 12001: which provides commands that allow you to point at an option and change its ! 12002: value: ! 12003: ! 12004: @table @kbd ! 12005: @item s ! 12006: Set the variable point is in or near to a new value read using the ! 12007: minibuffer. ! 12008: @item x ! 12009: Toggle the variable point is in or near: if the value was @code{nil}, ! 12010: it becomes @code{t}; otherwise it becomes @code{nil}. ! 12011: @item 1 ! 12012: Set the variable point is in or near to @code{t}. ! 12013: @item 0 ! 12014: Set the variable point is in or near to @code{nil}. ! 12015: @item n ! 12016: @itemx p ! 12017: Move to the next or previous variable. ! 12018: @end table ! 12019: ! 12020: @node Locals, File Variables, Edit Options, Variables ! 12021: @subsection Local Variables ! 12022: ! 12023: @table @kbd ! 12024: @item M-x make-local-variable ! 12025: Make a variable have a local value in the current buffer. ! 12026: @item M-x kill-local-variable ! 12027: Make a variable use its global value in the current buffer. ! 12028: @item M-x make-variable-buffer-local ! 12029: Mark a variable so that setting it will make it local to the ! 12030: buffer that is current at that time. ! 12031: @end table ! 12032: ! 12033: @cindex local variables ! 12034: Any variable can be made @dfn{local} to a specific Emacs buffer. This ! 12035: means that its value in that buffer is independent of its value in other ! 12036: buffers. A few variables are always local in every buffer. Every other ! 12037: Emacs variable has a @dfn{global} value which is in effect in all buffers ! 12038: that have not made the variable local. ! 12039: ! 12040: Major modes always make the variables they set local to the buffer. ! 12041: This is why changing major modes in one buffer has no effect on other ! 12042: buffers. ! 12043: ! 12044: @findex make-local-variable ! 12045: @kbd{M-x make-local-variable} reads the name of a variable and makes it ! 12046: local to the current buffer. Further changes in this buffer will not ! 12047: affect others, and further changes in the global value will not affect this ! 12048: buffer. ! 12049: ! 12050: @findex make-variable-buffer-local ! 12051: @cindex per-buffer variables ! 12052: @kbd{M-x make-variable-buffer-local} reads the name of a variable and ! 12053: changes the future behavior of the variable so that it will become local ! 12054: automatically when it is set. More precisely, once a variable has been ! 12055: marked in this way, the usual ways of setting the variable will ! 12056: automatically do @code{make-local-variable} first. We call such variables ! 12057: @dfn{per-buffer} variables. ! 12058: ! 12059: Some important variables have been marked per-buffer already. These include ! 12060: @code{abbrev-mode}, @code{auto-fill-hook}, @code{case-fold-search}, ! 12061: @code{comment-column}, @code{ctl-arrow}, @code{fill-column}, ! 12062: @code{fill-prefix}, @code{indent-tabs-mode}, @code{left-margin}, ! 12063: @code{mode-line-format}, @code{overwrite-mode},@* ! 12064: @code{selective-display-ellipses}, @code{selective-display}, ! 12065: @code{tab-width}, and @code{truncate-lines}. Some other variables are ! 12066: always local in every buffer, but they are used for internal purposes.@refill ! 12067: ! 12068: @findex kill-local-variable ! 12069: @kbd{M-x kill-local-variable} reads the name of a variable and makes it ! 12070: cease to be local to the current buffer. The global value of the variable ! 12071: henceforth is in effect in this buffer. Setting the major mode kills all ! 12072: the local variables of the buffer. ! 12073: ! 12074: @findex setq-default ! 12075: To set the global value of a variable, regardless of whether the ! 12076: variable has a local value in the current buffer, you can use the ! 12077: Lisp function @code{setq-default}. It works like @code{setq}. ! 12078: If there is a local value in the current buffer, the local value is ! 12079: not affected by @code{setq-default}; thus, the new global value may ! 12080: not be visible until you switch to another buffer. For example, ! 12081: ! 12082: @example ! 12083: (setq-default fill-column 75) ! 12084: @end example ! 12085: ! 12086: @noindent ! 12087: @code{setq-default} is the only way to set the global value of a variable ! 12088: that has been marked with @code{make-variable-buffer-local}. ! 12089: ! 12090: @findex default-value ! 12091: Programs can look at a variable's default value with @code{default-value}. ! 12092: This function takes a symbol as argument and returns its default value. ! 12093: The argument is evaluated; usually you must quote it explicitly. For ! 12094: example, ! 12095: ! 12096: @example ! 12097: (default-value 'fill-column) ! 12098: @end example ! 12099: ! 12100: @node File Variables,, Locals, Variables ! 12101: @subsection Local Variables in Files ! 12102: @cindex local variables in files ! 12103: ! 12104: A file can contain a @dfn{local variables list}, which specifies the ! 12105: values to use for certain Emacs variables when that file is edited. ! 12106: Visiting the file checks for a local variables list and makes each variable ! 12107: in the list local to the buffer in which the file is visited, with the ! 12108: value specified in the file. ! 12109: ! 12110: A local variables list goes near the end of the file, in the last page. ! 12111: (It is often best to put it on a page by itself.) The local variables list ! 12112: starts with a line containing the string @samp{Local Variables:}, and ends ! 12113: with a line containing the string @samp{End:}. In between come the ! 12114: variable names and values, one set per line, as @samp{@var{variable}:@: ! 12115: @var{value}}. The @var{value}s are not evaluated; they are used literally. ! 12116: ! 12117: The line which starts the local variables list does not have to say just ! 12118: @samp{Local Variables:}. If there is other text before @samp{Local ! 12119: Variables:}, that text is called the @dfn{prefix}, and if there is other ! 12120: text after, that is called the @dfn{suffix}. If these are present, each ! 12121: entry in the local variables list should have the prefix before it and the ! 12122: suffix after it. This includes the @samp{End:} line. The prefix and ! 12123: suffix are included to disguise the local variables list as a comment so ! 12124: that the compiler or text formatter will not be perplexed by it. If you do ! 12125: not need to disguise the local variables list as a comment in this way, do ! 12126: not bother with a prefix or a suffix.@refill ! 12127: ! 12128: Two ``variable'' names are special in a local variables list: a value for ! 12129: the variable @code{mode} really sets the major mode, and a value for the ! 12130: variable @code{eval} is simply evaluated as an expression and the value is ! 12131: ignored. These are not real variables; setting such variables in any other ! 12132: context has no such effect. If @code{mode} is used in a local variables ! 12133: list, it should be the first entry in the list. ! 12134: ! 12135: Here is an example of a local variables list: ! 12136: @example ! 12137: ;;; Local Variables: *** ! 12138: ;;; mode:lisp *** ! 12139: ;;; comment-column:0 *** ! 12140: ;;; comment-start: ";;; " *** ! 12141: ;;; comment-end:"***" *** ! 12142: ;;; End: *** ! 12143: @end example ! 12144: ! 12145: Note that the prefix is @samp{;;; } and the suffix is @samp{ ***}. Note also ! 12146: that comments in the file begin with and end with the same strings. ! 12147: Presumably the file contains code in a language which is like Lisp ! 12148: (like it enough for Lisp mode to be useful) but in which comments start ! 12149: and end in that way. The prefix and suffix are used in the local ! 12150: variables list to make the list appear as comments when the file is read ! 12151: by the compiler or interpreter for that language. ! 12152: ! 12153: The start of the local variables list must be no more than 3000 ! 12154: characters from the end of the file, and must be in the last page if the ! 12155: file is divided into pages. Otherwise, Emacs will not notice it is there. ! 12156: The purpose of this is so that a stray @samp{Local Variables:}@: not in the ! 12157: last page does not confuse Emacs, and so that visiting a long file that is ! 12158: all one page and has no local variables list need not take the time to ! 12159: search the whole file. ! 12160: ! 12161: You may be tempted to try to turn on Auto Fill mode with a local variable ! 12162: list. That is a mistake. The choice of Auto Fill mode or not is a matter ! 12163: of individual taste, not a matter of the contents of particular files. ! 12164: If you want to use Auto Fill, set up major mode hooks with your @file{.emacs} ! 12165: file to turn it on (when appropriate) for you alone (@pxref{Init File}). ! 12166: Don't try to use a local variable list that would impose your taste on ! 12167: everyone. ! 12168: ! 12169: @node Keyboard Macros, Key Bindings, Variables, Customization ! 12170: @section Keyboard Macros ! 12171: ! 12172: @cindex keyboard macros ! 12173: A @dfn{keyboard macro} is a command defined by the user to abbreviate a ! 12174: sequence of keys. For example, if you discover that you are about to type ! 12175: @kbd{C-n C-d} forty times, you can speed your work by defining a keyboard ! 12176: macro to do @kbd{C-n C-d} and calling it with a repeat count of forty. ! 12177: ! 12178: @c widecommands ! 12179: @table @kbd ! 12180: @item C-x ( ! 12181: Start defining a keyboard macro (@code{start-kbd-macro}). ! 12182: @item C-x ) ! 12183: End the definition of a keyboard macro (@code{end-kbd-macro}). ! 12184: @item C-x e ! 12185: Execute the most recent keyboard macro (@code{call-last-kbd-macro}). ! 12186: @item C-u C-x ( ! 12187: Re-execute last keyboard macro, then add more keys to its definition. ! 12188: @item C-x q ! 12189: When this point is reached during macro execution, ask for confirmation ! 12190: (@code{kbd-macro-query}). ! 12191: @item M-x name-last-kbd-macro ! 12192: Give a command name (for the duration of the session) to the most ! 12193: recently defined keyboard macro. ! 12194: @item M-x insert-kbd-macro ! 12195: Insert in the buffer a keyboard macro's definition, as Lisp code. ! 12196: @end table ! 12197: ! 12198: Keyboard macros differ from ordinary Emacs commands in that they are ! 12199: written in the Emacs command language rather than in Lisp. This makes it ! 12200: easier for the novice to write them, and makes them more convenient as ! 12201: temporary hacks. However, the Emacs command language is not powerful ! 12202: enough as a programming language to be useful for writing anything ! 12203: intelligent or general. For such things, Lisp must be used. ! 12204: ! 12205: You define a keyboard macro while executing the commands which are the ! 12206: definition. Put differently, as you are defining a keyboard macro, the ! 12207: definition is being executed for the first time. This way, you can see ! 12208: what the effects of your commands are, so that you don't have to figure ! 12209: them out in your head. When you are finished, the keyboard macro is ! 12210: defined and also has been, in effect, executed once. You can then do the ! 12211: whole thing over again by invoking the macro. ! 12212: ! 12213: @menu ! 12214: * Basic Kbd Macro:: Defining and running keyboard macros. ! 12215: * Save Kbd Macro:: Giving keyboard macros names; saving them in files. ! 12216: * Kbd Macro Query:: Keyboard macros that do different things each use. ! 12217: @end menu ! 12218: ! 12219: @node Basic Kbd Macro, Save Kbd Macro, Keyboard Macros, Keyboard Macros ! 12220: @subsection Basic Use ! 12221: ! 12222: @kindex C-x ( ! 12223: @kindex C-x ) ! 12224: @kindex C-x e ! 12225: @findex start-kbd-macro ! 12226: @findex end-kbd-macro ! 12227: @findex call-last-kbd-macro ! 12228: To start defining a keyboard macro, type the @kbd{C-x (} command ! 12229: (@code{start-kbd-macro}). From then on, your keys continue to be ! 12230: executed, but also become part of the definition of the macro. @samp{Def} ! 12231: appears in the mode line to remind you of what is going on. When you are ! 12232: finished, the @kbd{C-x )} command (@code{end-kbd-macro}) terminates the ! 12233: definition (without becoming part of it!). For example ! 12234: ! 12235: @example ! 12236: C-x ( M-F foo C-x ) ! 12237: @end example ! 12238: ! 12239: @noindent ! 12240: defines a macro to move forward a word and then insert @samp{foo}. ! 12241: ! 12242: The macro thus defined can be invoked again with the @kbd{C-x e} command ! 12243: (@code{call-last-kbd-macro}), which may be given a repeat count as a ! 12244: numeric argument to execute the macro many times. @kbd{C-x )} can also be ! 12245: given a repeat count as an argument, in which case it repeats the macro ! 12246: that many times right after defining it, but defining the macro counts as ! 12247: the first repetition (since it is executed as you define it). So, giving ! 12248: @kbd{C-x )} an argument of 4 executes the macro immediately 3 additional ! 12249: times. An argument of zero to @kbd{C-x e} or @kbd{C-x )} means repeat the ! 12250: macro indefinitely (until it gets an error or you type @kbd{C-g}). ! 12251: ! 12252: If you wish to repeat an operation at regularly spaced places in the ! 12253: text, define a macro and include as part of the macro the commands to move ! 12254: to the next place you want to use it. For example, if you want to change ! 12255: each line, you should position point at the start of a line, and define a ! 12256: macro to change that line and leave point at the start of the next line. ! 12257: Then repeating the macro will operate on successive lines. ! 12258: ! 12259: After you have terminated the definition of a keyboard macro, you can add ! 12260: to the end of its definition by typing @kbd{C-u C-x (}. This is equivalent ! 12261: to plain @kbd{C-x (} followed by retyping the whole definition so far. As ! 12262: a consequence it re-executes the macro as previously defined. ! 12263: ! 12264: @node Save Kbd Macro, Kbd Macro Query, Basic Kbd Macro, Keyboard Macros ! 12265: @subsection Naming and Saving Keyboard Macros ! 12266: ! 12267: @findex name-last-kbd-macro ! 12268: If you wish to save a keyboard macro for longer than until you define the ! 12269: next one, you must give it a name using @kbd{M-x name-last-kbd-macro}. ! 12270: This reads a name as an argument using the minibuffer and defines that name ! 12271: to execute the macro. The macro name is a Lisp symbol, and defining it in ! 12272: this way makes it a valid command name for calling with @kbd{M-x} or for ! 12273: binding a key to with @code{global-set-key} (@pxref{Keymaps}). If you ! 12274: specify a name that has a prior definition other than another keyboard ! 12275: macro, an error message is printed and nothing is changed. ! 12276: ! 12277: @findex insert-kbd-macro ! 12278: Once a macro has a command name, you can save its definition in a file. ! 12279: Then it can be used in another editing session. First visit the file ! 12280: you want to save the definition in. Then use the command ! 12281: ! 12282: @example ! 12283: M-x insert-kbd-macro @key{RET} @var{macroname} @key{RET} ! 12284: @end example ! 12285: ! 12286: @noindent ! 12287: This inserts some Lisp code that, when executed later, will define the same ! 12288: macro with the same definition it has now. You need not understand Lisp ! 12289: code to do this, because @code{insert-kbd-macro} writes the Lisp code for you. ! 12290: Then save the file. The file can be loaded with @code{load-file} ! 12291: (@pxref{Lisp Libraries}). If the file you save in is your init file ! 12292: @file{~/.emacs} (@pxref{Init File}) then the macro will be defined each ! 12293: time you run Emacs. ! 12294: ! 12295: If you give @code{insert-kbd-macro} a prefix argument, it makes ! 12296: additional Lisp code to record the keys (if any) that you have bound to the ! 12297: keyboard macro, so that the macro will be reassigned the same keys when you ! 12298: load the file. ! 12299: ! 12300: @node Kbd Macro Query,, Save Kbd Macro, Keyboard Macros ! 12301: @subsection Executing Macros with Variations ! 12302: ! 12303: @kindex C-x q ! 12304: @findex kbd-macro-query ! 12305: Using @kbd{C-x q} (@code{kbd-macro-query}), you can get an effect similar ! 12306: to that of @code{query-replace}, where the macro asks you each time around ! 12307: whether to make a change. When you are defining the macro, type @kbd{C-x ! 12308: q} at the point where you want the query to occur. During macro ! 12309: definition, the @kbd{C-x q} does nothing, but when the macro is invoked the ! 12310: @kbd{C-x q} reads a character from the terminal to decide whether to ! 12311: continue. ! 12312: ! 12313: The special answers are @key{SPC}, @key{DEL}, @kbd{C-d}, @kbd{C-l} and ! 12314: @kbd{C-r}. Any other character terminates execution of the keyboard macro ! 12315: and is then read as a command. @key{SPC} means to continue. @key{DEL} ! 12316: means to skip the remainder of this repetition of the macro, starting again ! 12317: from the beginning in the next repetition. @kbd{C-d} means to skip the ! 12318: remainder of this repetition and cancel further repetition. @kbd{C-l} ! 12319: redraws the screen and asks you again for a character to say what to do. ! 12320: @kbd{C-r} enters a recursive editing level, in which you can perform ! 12321: editing which is not part of the macro. When you exit the recursive edit ! 12322: using @kbd{C-M-c}, you are asked again how to continue with the keyboard ! 12323: macro. If you type a @key{SPC} at this time, the rest of the macro ! 12324: definition is executed. It is up to you to leave point and the text in a ! 12325: state such that the rest of the macro will do what you want.@refill ! 12326: ! 12327: @kbd{C-u C-x q}, which is @kbd{C-x q} with a numeric argument, performs a ! 12328: different function. It enters a recursive edit reading input from the ! 12329: keyboard, both when you type it during the definition of the macro, and ! 12330: when it is executed from the macro. During definition, the editing you do ! 12331: inside the recursive edit does not become part of the macro. During macro ! 12332: execution, the recursive edit gives you a chance to do some particularized ! 12333: editing. @xref{Recursive Edit}. ! 12334: ! 12335: @node Key Bindings, Syntax, Keyboard Macros, Customization ! 12336: @section Customizing Key Bindings ! 12337: ! 12338: This section deals with the @dfn{keymaps} which define the bindings ! 12339: between keys and functions, and shows how you can customize these bindings. ! 12340: @cindex command ! 12341: @cindex function ! 12342: @cindex command name ! 12343: ! 12344: A command is a Lisp function whose definition provides for interactive ! 12345: use. Like every Lisp function, a command has a function name, a Lisp ! 12346: symbol whose name usually consists of lower case letters and hyphens. ! 12347: ! 12348: @menu ! 12349: * Keymaps:: Definition of the keymap data structure. ! 12350: Names of Emacs's standard keymaps. ! 12351: * Rebinding:: How to redefine one key's meaning conveniently. ! 12352: * Disabling:: Disabling a command means confirmation is required ! 12353: before it can be executed. This is done to protect ! 12354: beginners from surprises. ! 12355: @end menu ! 12356: ! 12357: @node Keymaps, Rebinding, Key Bindings, Key Bindings ! 12358: @subsection Keymaps ! 12359: @cindex keymap ! 12360: ! 12361: @cindex global keymap ! 12362: @vindex global-map ! 12363: The bindings between characters and command functions are recorded in ! 12364: data structures called @dfn{keymaps}. Emacs has many of these. One, the ! 12365: @dfn{global} keymap, defines the meanings of the single-character keys that ! 12366: are defined regardless of major mode. It is the value of the variable ! 12367: @code{global-map}. ! 12368: ! 12369: @cindex local keymap ! 12370: @vindex c-mode-map ! 12371: @vindex lisp-mode-map ! 12372: Each major mode has another keymap, its @dfn{local keymap}, which ! 12373: contains overriding definitions for the single-character keys that are to ! 12374: be redefined in that mode. Each buffer records which local keymap is ! 12375: installed for it at any time, and the current buffer's local keymap is the ! 12376: only one that directly affects command execution. The local keymaps for ! 12377: Lisp mode, C mode, and many other major modes always exist even when not in ! 12378: use. They are the values of the variables @code{lisp-mode-map}, ! 12379: @code{c-mode-map}, and so on. For major modes less often used, the local ! 12380: keymap is sometimes constructed only when the mode is used for the first ! 12381: time in a session. This is to save space. ! 12382: ! 12383: @cindex minibuffer ! 12384: @vindex minibuffer-local-map ! 12385: @vindex minibuffer-local-ns-map ! 12386: @vindex minibuffer-local-completion-map ! 12387: @vindex minibuffer-local-must-match-map ! 12388: @vindex repeat-complex-command-map ! 12389: There are local keymaps for the minibuffer too; they contain various ! 12390: completion and exit commands. ! 12391: ! 12392: @itemize @bullet ! 12393: @item ! 12394: @code{minibuffer-local-map} is used for ordinary input (no completion). ! 12395: @item ! 12396: @code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits ! 12397: just like @key{RET}. This is used mainly for Mocklisp compatibility. ! 12398: @item ! 12399: @code{minibuffer-local-completion-map} is for permissive completion. ! 12400: @item ! 12401: @code{minibuffer-local-must-match-map} is for strict completion and ! 12402: for cautious completion. ! 12403: @item ! 12404: @code{repeat-complex-command-map} is for use in @kbd{C-x @key{ESC}}. ! 12405: @end itemize ! 12406: ! 12407: @vindex ctl-x-map ! 12408: @vindex help-map ! 12409: @vindex esc-map ! 12410: Finally, each prefix key has a keymap which defines the key sequences ! 12411: that start with it. For example, @code{ctl-x-map} is the keymap used for ! 12412: characters following a @kbd{C-x}. ! 12413: ! 12414: @itemize @bullet ! 12415: @item ! 12416: @code{ctl-x-map} is the variable name for the map used for characters that ! 12417: follow @kbd{C-x}. ! 12418: @item ! 12419: @code{help-map} is used for characters that follow @kbd{C-h}. ! 12420: @item ! 12421: @code{esc-map} is for characters that follow @key{ESC}. Thus, all Meta ! 12422: characters are actually defined by this map. ! 12423: @item ! 12424: @code{ctl-x-4-map} is for characters that follow @kbd{C-x 4}. ! 12425: @item ! 12426: @code{mode-specific-map} is for characters that follow @kbd{C-c}. ! 12427: @end itemize ! 12428: ! 12429: The definition of a prefix key is just the keymap to use for looking up ! 12430: the following character. Actually, the definition is sometimes a Lisp ! 12431: symbol whose function definition is the following character keymap. The ! 12432: effect is the same, but it provides a command name for the prefix key that ! 12433: can be used as a description of what the prefix key is for. Thus, the ! 12434: binding of @kbd{C-x} is the symbol @code{Ctl-X-Prefix}, whose function ! 12435: definition is the keymap for @kbd{C-x} commands, the value of ! 12436: @code{ctl-x-map}.@refill ! 12437: ! 12438: Prefix key definitions of this sort can appear in either the global map ! 12439: or a local map. The definitions of @kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} ! 12440: as prefix keys appear in the global map, so these prefix keys are always ! 12441: available. Major modes can locally redefine a key as a prefix by putting ! 12442: a prefix key definition for it in the local map.@refill ! 12443: ! 12444: A mode can also put a prefix definition of a global prefix character such ! 12445: as @kbd{C-x} into its local map. This is how major modes override the ! 12446: definitions of certain keys that start with @kbd{C-x}. This case is ! 12447: special, because the local definition does not entirely replace the global ! 12448: one. When both the global and local definitions of a key are other ! 12449: keymaps, the next character is looked up in both keymaps, with the local ! 12450: definition overriding the global one as usual. So, the character after the ! 12451: @kbd{C-x} is looked up in both the major mode's own keymap for redefined ! 12452: @kbd{C-x} commands and in @code{ctl-x-map}. If the major mode's own keymap ! 12453: for @kbd{C-x} commands contains @code{nil}, the definition from the global ! 12454: keymap for @kbd{C-x} commands is used.@refill ! 12455: ! 12456: @cindex sparse keymap ! 12457: A keymap is actually a Lisp object. The simplest form of keymap is a ! 12458: Lisp vector of length 128. The binding for a character in such a keymap is ! 12459: found by indexing into the vector with the character as an index. A keymap ! 12460: can also be a Lisp list whose car is the symbol @code{keymap} and whose ! 12461: remaining elements are pairs of the form @code{(@var{char} .@: @var{binding})}. ! 12462: Such lists are called @dfn{sparse keymaps} because they are used when most ! 12463: of the characters' entries will be @code{nil}. Sparse keymaps are used ! 12464: mainly for prefix characters. ! 12465: ! 12466: Keymaps are only of length 128, so what about Meta characters, whose ! 12467: codes are from 128 to 255? A key that contains a Meta character actually ! 12468: represents it as a sequence of two characters, the first of which is ! 12469: @key{ESC}. So the key @kbd{M-a} is really represented as @kbd{@key{ESC} ! 12470: a}, and its binding is found at the slot for @samp{a} in ! 12471: @code{esc-map}.@refill ! 12472: ! 12473: @node Rebinding, Disabling, Keymaps, Key Bindings ! 12474: @subsection Changing Key Bindings Interactively ! 12475: @cindex key rebinding, this session ! 12476: @cindex rebinding keys, this session ! 12477: @cindex rebinding keys, this session ! 12478: ! 12479: The way to redefine an Emacs key is to change its entry in a keymap. ! 12480: You can change the global keymap, in which case the change is effective in ! 12481: all major modes (except those that have their own overriding local ! 12482: definitions for the same key). Or you can change the current buffer's ! 12483: local map, which affects all buffers using the same major mode. ! 12484: @findex global-set-key ! 12485: @findex local-set-key ! 12486: ! 12487: @table @kbd ! 12488: @item M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET} ! 12489: Defines @var{key} globally to run @var{cmd}. ! 12490: @item M-x local-set-key @key{RET} @var{key} @var{cmd} @key{RET} ! 12491: Defines @var{key} locally (in the major mode now in effect) to run ! 12492: @var{cmd}. ! 12493: @end table ! 12494: ! 12495: For example, ! 12496: ! 12497: @example ! 12498: M-x global-set-key @key{RET} C-f next-line @key{RET} ! 12499: @end example ! 12500: ! 12501: @noindent ! 12502: would redefine @kbd{C-f} to move down a line. The fact that @var{cmd} is ! 12503: read second makes it serve as a kind of confirmation for @var{key}. ! 12504: ! 12505: These functions offer no way to specify a particular prefix keymap as the ! 12506: one to redefine in, but that is not necessary, as you can include prefixes ! 12507: in @var{key}. @var{key} is read by reading characters one by one until ! 12508: they amount to a complete key (that is, not a prefix key). Thus, if you ! 12509: type @kbd{C-f} for @var{key}, that's the end; the minibuffer is entered ! 12510: immediately to read @var{cmd}. But if you type @kbd{C-x}, another ! 12511: character is read; if that is @kbd{4}, another character is read, and so ! 12512: on. For example,@refill ! 12513: ! 12514: @example ! 12515: M-x global-set-key @key{RET} C-x 4 $ spell-other-window @key{RET} ! 12516: @end example ! 12517: ! 12518: @noindent ! 12519: would redefine @kbd{C-x 4 $} to run the (fictitious) command ! 12520: @code{spell-other-window}. ! 12521: ! 12522: @findex define-key ! 12523: @findex substitute-key-definition ! 12524: The most general way to modify a keymap is the function @code{define-key}, ! 12525: used in Lisp code (such as your @file{.emacs} file). @code{define-key} ! 12526: takes three arguments: the keymap, the key to modify in it, and the new ! 12527: definition. @xref{Init File}, for an example. @code{substitute-key-definition} ! 12528: is used similarly; it takes three arguments, an old definition, a new ! 12529: definition and a keymap, and redefines in that keymap all keys that were ! 12530: previously defined with the old definition to have the new definition ! 12531: instead. ! 12532: ! 12533: @node Disabling,, Rebinding, Key Bindings ! 12534: @subsection Disabling Commands ! 12535: @cindex disabled command ! 12536: ! 12537: Disabling a command marks the command as requiring confirmation before it ! 12538: can be executed. The purpose of disabling a command is to prevent ! 12539: beginning users from executing it by accident and being confused. ! 12540: ! 12541: The direct mechanism for disabling a command is to have a non-@code{nil} ! 12542: @code{disabled} property on the Lisp symbol for the command. These ! 12543: properties are normally set up by the user's @file{.emacs} file with ! 12544: Lisp expressions such as ! 12545: ! 12546: @example ! 12547: (put 'delete-region 'disabled t) ! 12548: @end example ! 12549: ! 12550: If the value of the @code{disabled} property is a string, that string ! 12551: is included in the message printed when the command is used: ! 12552: ! 12553: @example ! 12554: (put 'delete-region 'disabled ! 12555: "Text deleted this way cannot be yanked back!\n") ! 12556: @end example ! 12557: ! 12558: @findex disable-command ! 12559: @findex enable-command ! 12560: You can make a command disabled either by editing the @file{.emacs} file ! 12561: directly or with the command @kbd{M-x disable-command}, which edits the ! 12562: @file{.emacs} file for you. @xref{Init File}. ! 12563: ! 12564: Attempting to invoke a disabled command interactively in Emacs causes the ! 12565: display of a window containing the command's name, its documentation, and ! 12566: some instructions on what to do immediately; then Emacs asks for input ! 12567: saying whether to execute the command as requested, enable it and execute, ! 12568: or cancel it. If you decide to enable the command, you are asked whether to ! 12569: do this permanently or just for the current session. Enabling permanently ! 12570: works by automatically editing your @file{.emacs} file. You can use ! 12571: @kbd{M-x enable-command} at any time to enable any command permanently. ! 12572: ! 12573: Whether a command is disabled is independent of what key is used to ! 12574: invoke it; it also applies if the command is invoked using @kbd{M-x}. ! 12575: Disabling a command has no effect on calling it as a function from Lisp ! 12576: programs. ! 12577: ! 12578: @node Syntax, Init File, Key Bindings, Customization ! 12579: @section The Syntax Table ! 12580: @cindex syntax table ! 12581: ! 12582: All the Emacs commands which parse words or balance parentheses are ! 12583: controlled by the @dfn{syntax table}. The syntax table says which ! 12584: characters are opening delimiters, which are parts of words, which are ! 12585: string quotes, and so on. Actually, each major mode has its own syntax ! 12586: table (though sometimes related major modes use the same one) which it ! 12587: installs in each buffer that uses that major mode. The syntax table ! 12588: installed in the current buffer is the one that all commands use, so we ! 12589: call it ``the'' syntax table. A syntax table is a Lisp object, a vector of ! 12590: length 256 whose elements are numbers. ! 12591: ! 12592: @menu ! 12593: * Entry: Syntax Entry. What the syntax table records for each character. ! 12594: * Change: Syntax Change. How to change the information. ! 12595: @end menu ! 12596: ! 12597: @node Syntax Entry, Syntax Change, Syntax, Syntax ! 12598: @subsection Information about Each Character ! 12599: ! 12600: The syntax table entry for a character is a number that encodes six ! 12601: pieces of information: ! 12602: ! 12603: @itemize @bullet ! 12604: @item ! 12605: The syntactic class of the character, represented as a small integer. ! 12606: @item ! 12607: The matching delimiter, for delimiter characters only. ! 12608: The matching delimiter of @samp{(} is @samp{)}, and vice versa. ! 12609: @item ! 12610: A flag saying whether the character is the first character of a ! 12611: two-character comment starting sequence. ! 12612: @item ! 12613: A flag saying whether the character is the second character of a ! 12614: two-character comment starting sequence. ! 12615: @item ! 12616: A flag saying whether the character is the first character of a ! 12617: two-character comment ending sequence. ! 12618: @item ! 12619: A flag saying whether the character is the second character of a ! 12620: two-character comment ending sequence. ! 12621: @end itemize ! 12622: ! 12623: The syntactic classes are stored internally as small integers, but are ! 12624: usually described to or by the user with characters. For example, @samp{(} ! 12625: is used to specify the syntactic class of opening delimiters. Here is a ! 12626: table of syntactic classes, with the characters that specify them. ! 12627: ! 12628: @table @samp ! 12629: @item @w{ } ! 12630: The class of whitespace characters. ! 12631: @item w ! 12632: The class of word-constituent characters. ! 12633: @item _ ! 12634: The class of characters that are part of symbol names but not words. ! 12635: This class is represented by @samp{_} because the character @samp{_} ! 12636: has this class in both C and Lisp. ! 12637: @item . ! 12638: The class of punctuation characters that do not fit into any other ! 12639: special class. ! 12640: @item ( ! 12641: The class of opening delimiters. ! 12642: @item ) ! 12643: The class of closing delimiters. ! 12644: @item ' ! 12645: The class of expression-adhering characters. These characters are ! 12646: part of a symbol if found within or adjacent to one, and are part ! 12647: of a following expression if immediately preceding one, but are like ! 12648: whitespace if surrounded by whitespace. ! 12649: @item " ! 12650: The class of string-quote characters. They match each other in pairs, ! 12651: and the characters within the pair all lose their syntactic ! 12652: significance except for the @samp{\} and @samp{/} classes of escape ! 12653: characters, which can be used to include a string-quote inside the ! 12654: string. ! 12655: @item $ ! 12656: The class of self-matching delimiters. This is intended for @TeX{}'s ! 12657: @samp{$}, which is used both to enter and leave math mode. Thus, ! 12658: a pair of matching @samp{$} characters surround each piece of math mode ! 12659: @TeX{} input. A pair of adjacent @samp{$} characters act like a single ! 12660: one for purposes of matching ! 12661: ! 12662: @item / ! 12663: The class of escape characters that always just deny the following ! 12664: character its special syntactic significance. The character after one ! 12665: of these escapes is always treated as alphabetic. ! 12666: @item \ ! 12667: The class of C-style escape characters. In practice, these are ! 12668: treated just like @samp{/}-class characters, because the extra ! 12669: possibilities for C escapes (such as being followed by digits) have no ! 12670: effect on where the containing expression ends. ! 12671: @item < ! 12672: The class of comment-starting characters. Only single-character ! 12673: comment starters (such as @samp{;} in Lisp mode) are represented this ! 12674: way. ! 12675: @item > ! 12676: The class of comment-ending characters. Newline has this syntax in ! 12677: Lisp mode. ! 12678: @end table ! 12679: ! 12680: @vindex parse-sexp-ignore-comments ! 12681: The characters flagged as part of two-character comment delimiters can ! 12682: have other syntactic functions most of the time. For example, @samp{/} and ! 12683: @samp{*} in C code, when found separately, have nothing to do with ! 12684: comments. The comment-delimiter significance overrides when the pair of ! 12685: characters occur together in the proper order. Only the list and sexp ! 12686: commands use the syntax table to find comments; the commands specifically ! 12687: for comments have other variables that tell them where to find comments. ! 12688: And the list and sexp commands notice comments only if ! 12689: @code{parse-sexp-ignore-comments} is non-@code{nil}. This variable is set ! 12690: to @code{nil} in modes where comment-terminator sequences are liable to ! 12691: appear where there is no comment; for example, in Lisp mode where the ! 12692: comment terminator is a newline but not every newline ends a comment. ! 12693: ! 12694: @node Syntax Change,, Syntax Entry, Syntax ! 12695: @subsection Altering Syntax Information ! 12696: ! 12697: It is possible to alter a character's syntax table entry by storing a new ! 12698: number in the appropriate element of the syntax table, but it would be hard ! 12699: to determine what number to use. Therefore, Emacs provides a command that ! 12700: allows you to specify the syntactic properties of a character in a ! 12701: convenient way. ! 12702: ! 12703: @findex modify-syntax-entry ! 12704: @kbd{M-x modify-syntax-entry} is the command to change a character's ! 12705: syntax. It can be used interactively, and is also the means used by major ! 12706: modes to initialize their own syntax tables. Its first argument is the ! 12707: character to change. The second argument is a string that specifies the ! 12708: new syntax. When called from Lisp code, there is a third, optional ! 12709: argument, which specifies the syntax table in which to make the change. If ! 12710: not supplied, or if this command is called interactively, the third ! 12711: argument defaults to the current buffer's syntax table. ! 12712: ! 12713: @enumerate ! 12714: @item ! 12715: The first character in the string specifies the syntactic class. It ! 12716: is one of the characters in the previous table (@pxref{Syntax Entry}). ! 12717: ! 12718: @item ! 12719: The second character is the matching delimiter. For a character that ! 12720: is not an opening or closing delimiter, this should be a space, and may ! 12721: be omitted if no following characters are needed. ! 12722: ! 12723: @item ! 12724: The remaining characters are flags. The flag characters allowed are ! 12725: ! 12726: @table @samp ! 12727: @item 1 ! 12728: Flag this character as the first of a two-character comment starting sequence. ! 12729: @item 2 ! 12730: Flag this character as the second of a two-character comment starting sequence. ! 12731: @item 3 ! 12732: Flag this character as the first of a two-character comment ending sequence. ! 12733: @item 4 ! 12734: Flag this character as the second of a two-character comment ending sequence. ! 12735: @end table ! 12736: @end enumerate ! 12737: ! 12738: @kindex C-h s ! 12739: @findex describe-syntax ! 12740: A description of the contents of the current syntax table can be ! 12741: displayed with @kbd{C-h s} (@code{describe-syntax}). The description of ! 12742: each character includes both the string you would have to give to ! 12743: @code{modify-syntax-entry} to set up that character's current syntax, and ! 12744: some English to explain that string if necessary. ! 12745: ! 12746: @node Init File,, Syntax, Customization ! 12747: @section The Init File, .emacs ! 12748: @cindex init file ! 12749: @cindex Emacs initialization file ! 12750: @cindex key rebinding, permanent ! 12751: @cindex rebinding keys, permanently ! 12752: ! 12753: When Emacs is started, it normally loads the file @file{.emacs} in your ! 12754: home directory. This file, if it exists, should contain Lisp code. It is ! 12755: called your @dfn{init file}. The command line switches @samp{-q} and ! 12756: @samp{-u} can be used to tell Emacs whether to load an init file ! 12757: (@pxref{Entering Emacs}). ! 12758: ! 12759: There can also be a @dfn{default init file}, which is the library named ! 12760: @file{default.el}, found via the standard search path for libraries. The ! 12761: Emacs distribution contains no such library; your site may create one for ! 12762: local customizations. If this library exists, it is loaded whenever you ! 12763: start Emacs. But your init file, if any, is loaded first; if it sets ! 12764: @code{inhibit-default-init} non-@code{nil}, then @file{default} is not ! 12765: loaded. ! 12766: ! 12767: If you have a large amount of code in your @file{.emacs} file, you ! 12768: should move it into another file named @file{@var{something}.el}, ! 12769: byte-compile it (@pxref{Lisp Libraries}), and make your @file{.emacs} ! 12770: file load the other file using @code{load}. ! 12771: ! 12772: @menu ! 12773: * Init Syntax:: Syntax of constants in Emacs Lisp. ! 12774: * Init Examples:: How to do some things with an init file. ! 12775: * Terminal Init:: Each terminal type can have an init file. ! 12776: @end menu ! 12777: ! 12778: @node Init Syntax, Init Examples, Init File, Init File ! 12779: @subsection Init File Syntax ! 12780: ! 12781: The @file{.emacs} file contains one or more Lisp function call ! 12782: expressions. Each of these consists of a function name followed by ! 12783: arguments, all surrounded by parentheses. For example, @code{(setq ! 12784: fill-column 60)} represents a call to the function @code{setq} which is ! 12785: used to set the variable @code{fill-column} (@pxref{Filling}) to 60. ! 12786: ! 12787: The second argument to @code{setq} is an expression for the new value of ! 12788: the variable. This can be a constant, a variable, or a function call ! 12789: expression. In @file{.emacs}, constants are used most of the time. They can be: ! 12790: ! 12791: @table @asis ! 12792: @item Numbers: ! 12793: Numbers are written in decimal, with an optional initial minus sign. ! 12794: ! 12795: @item Strings: ! 12796: Lisp string syntax is the same as C string syntax with a few extra ! 12797: features. Use a double-quote character to begin and end a string constant. ! 12798: ! 12799: Newlines and special characters may be present literally in strings. They ! 12800: can also be represented as backslash sequences: @samp{\n} for newline, ! 12801: @samp{\b} for backspace, @samp{\r} for carriage return, @samp{\t} for tab, ! 12802: @samp{\f} for formfeed (control-l), @samp{\e} for escape, @samp{\\} for a ! 12803: backslash, @samp{\"} for a double-quote, or @samp{\@var{ooo}} for the ! 12804: character whose octal code is @var{ooo}. Backslash and double-quote are ! 12805: the only characters for which backslash sequences are mandatory. ! 12806: ! 12807: @samp{\C-} can be used as a prefix for a control character, as in ! 12808: @samp{\C-s} for ASCII Control-S, and @samp{\M-} can be used as a prefix for ! 12809: a meta character, as in @samp{\M-a} for Meta-A or @samp{\M-\C-a} for ! 12810: Control-Meta-A.@refill ! 12811: ! 12812: @item Characters: ! 12813: Lisp character constant syntax consists of a @samp{?} followed by ! 12814: either a character or an escape sequence starting with @samp{\}. ! 12815: Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}. Note that ! 12816: strings and characters are not interchangeable in Lisp; some contexts ! 12817: require one and some contexts require the other. ! 12818: ! 12819: @item True: ! 12820: @code{t} stands for `true'. ! 12821: ! 12822: @item False: ! 12823: @code{nil} stands for `false'. ! 12824: ! 12825: @item Other Lisp objects: ! 12826: Write a single-quote (') followed by the Lisp object you want. ! 12827: @end table ! 12828: ! 12829: @node Init Examples, Terminal Init, Init Syntax, Init File ! 12830: @subsection Init File Examples ! 12831: ! 12832: Here are some examples of doing certain commonly desired things with ! 12833: Lisp expressions: ! 12834: ! 12835: @itemize @bullet ! 12836: @item ! 12837: Make @key{TAB} in C mode just insert a tab if point is in the middle of a ! 12838: line. ! 12839: ! 12840: @example ! 12841: (setq c-tab-always-indent nil) ! 12842: @end example ! 12843: ! 12844: Here we have a variable whose value is normally @code{t} for `true' ! 12845: and the alternative is @code{nil} for `false'. ! 12846: ! 12847: @item ! 12848: Make searches case sensitive by default (in all buffers that do not ! 12849: override this). ! 12850: ! 12851: @example ! 12852: (setq-default case-fold-search nil) ! 12853: @end example ! 12854: ! 12855: This sets the default value, which is effective in all buffers that do ! 12856: not have local values for the variable. Setting @code{case-fold-search} ! 12857: with @code{setq} affects only the current buffer's local value, which ! 12858: is not what you probably want to do in an init file. ! 12859: ! 12860: @item ! 12861: Make Text mode the default mode for new buffers. ! 12862: ! 12863: @example ! 12864: (setq default-major-mode 'text-mode) ! 12865: @end example ! 12866: ! 12867: Note that @code{text-mode} is used because it is the command for entering ! 12868: the mode we want. A single-quote is written before it to make a symbol ! 12869: constant; otherwise, @code{text-mode} would be treated as a variable name. ! 12870: ! 12871: @item ! 12872: Turn on Auto Fill mode automatically in Text mode and related modes. ! 12873: ! 12874: @example ! 12875: (setq text-mode-hook ! 12876: '(lambda () (auto-fill-mode 1))) ! 12877: @end example ! 12878: ! 12879: Here we have a variable whose value should be a Lisp function. The ! 12880: function we supply is a list starting with @code{lambda}, and a single ! 12881: quote is written in front of it to make it (for the purpose of this ! 12882: @code{setq}) a list constant rather than an expression. Lisp functions ! 12883: are not explained here, but for mode hooks it is enough to know that ! 12884: @code{(auto-fill-mode 1)} is an expression that will be executed when ! 12885: Text mode is entered, and you could replace it with any other expression ! 12886: that you like, or with several expressions in a row. ! 12887: ! 12888: @example ! 12889: (setq text-mode-hook 'turn-on-auto-fill) ! 12890: @end example ! 12891: ! 12892: This is another way to accomplish the same result. ! 12893: @code{turn-on-auto-fill} is a symbol whose function definition is ! 12894: @code{(lambda () (auto-fill-mode 1))}. ! 12895: ! 12896: @item ! 12897: Load the installed Lisp library named @file{foo} (actually a file ! 12898: @file{foo.elc} or @file{foo.el} in a standard Emacs directory). ! 12899: ! 12900: @example ! 12901: (load "foo") ! 12902: @end example ! 12903: ! 12904: When the argument to @code{load} is a relative pathname, not starting ! 12905: with @samp{/} or @samp{~}, @code{load} searches the directories in ! 12906: @code{load-path} (@pxref{Loading}). ! 12907: ! 12908: @item ! 12909: Load the compiled Lisp file @file{foo.elc} from your home directory. ! 12910: ! 12911: @example ! 12912: (load "~/foo.elc") ! 12913: @end example ! 12914: ! 12915: Here an absolute file name is used, so no searching is done. ! 12916: ! 12917: @item ! 12918: Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link}. ! 12919: ! 12920: @example ! 12921: (global-set-key "\C-xl" 'make-symbolic-link) ! 12922: @end example ! 12923: ! 12924: or ! 12925: ! 12926: @example ! 12927: (define-key global-map "\C-xl" 'make-symbolic-link) ! 12928: @end example ! 12929: ! 12930: Note once again the single-quote used to refer to the symbol ! 12931: @code{make-symbolic-link} instead of its value as a variable. ! 12932: ! 12933: @item ! 12934: Do the same thing for C mode only. ! 12935: ! 12936: @example ! 12937: (define-key c-mode-map "\C-xl" 'make-symbolic-link) ! 12938: @end example ! 12939: ! 12940: @item ! 12941: Redefine all keys which now run @code{next-line} in Fundamental mode ! 12942: so that they run @code{forward-line} instead. ! 12943: ! 12944: @example ! 12945: (substitute-key-definition 'next-line 'forward-line ! 12946: global-map) ! 12947: @end example ! 12948: ! 12949: @item ! 12950: Make @kbd{C-x C-v} undefined. ! 12951: ! 12952: @example ! 12953: (global-unset-key "\C-x\C-v") ! 12954: @end example ! 12955: ! 12956: One reason to undefine a key is so that you can make it a prefix. ! 12957: Simply defining @kbd{C-x C-v @var{anything}} would make @kbd{C-x C-v} ! 12958: a prefix, but @kbd{C-x C-v} must be freed of any non-prefix definition ! 12959: first. ! 12960: ! 12961: @item ! 12962: Make @samp{$} have the syntax of punctuation in Text mode. ! 12963: Note the use of a character constant for @samp{$}. ! 12964: ! 12965: @example ! 12966: (modify-syntax-entry ?\$ "." text-mode-syntax-table) ! 12967: @end example ! 12968: ! 12969: @item ! 12970: Enable the use of the command @code{eval-expression} without confirmation. ! 12971: ! 12972: @example ! 12973: (put 'eval-expression 'disabled nil) ! 12974: @end example ! 12975: @end itemize ! 12976: ! 12977: @node Terminal Init,, Init Examples, Init File ! 12978: @subsection Terminal-specific Initialization ! 12979: ! 12980: Each terminal type can have a Lisp library to be loaded into Emacs when ! 12981: it is run on that type of terminal. For a terminal type named ! 12982: @var{termtype}, the library is called @file{term/@var{termtype}} and it is ! 12983: found by searching the directories @code{load-path} as usual and trying the ! 12984: suffixes @samp{.elc} and @samp{.el}. Normally it appears in the ! 12985: subdirectory @file{term} of the directory where most Emacs libraries are ! 12986: kept.@refill ! 12987: ! 12988: The usual purpose of the terminal-specific library is to define the ! 12989: escape sequences used by the terminal's function keys using the library ! 12990: @file{keypad.el}. See the file ! 12991: @file{term/vt100.el} for an example of how this is done.@refill ! 12992: ! 12993: When the terminal type contains a hyphen, only the part of the name ! 12994: before the first hyphen is significant in choosing the library name. ! 12995: Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use ! 12996: the library @file{term/aaa}. The code in the library can use ! 12997: @code{(getenv "TERM")} to find the full terminal type name.@refill ! 12998: ! 12999: @vindex term-file-prefix ! 13000: The library's name is constructed by concatenating the value of the ! 13001: variable @code{term-file-prefix} and the terminal type. Your @file{.emacs} ! 13002: file can prevent the loading of the terminal-specific library by setting ! 13003: @code{term-file-prefix} to @code{nil}. ! 13004: ! 13005: @vindex term-setup-hook ! 13006: The value of the variable @code{term-setup-hook}, if not @code{nil}, is ! 13007: called as a function of no arguments at the end of Emacs initialization, ! 13008: after both your @file{.emacs} file and any terminal-specific library have ! 13009: been read in. You can set the value in the @file{.emacs} file to override ! 13010: part of any of the terminal-specific libraries and to define ! 13011: initializations for terminals that do not have a library.@refill ! 13012: ! 13013: @iftex ! 13014: @chapter Correcting Mistakes (Yours or Emacs's) ! 13015: ! 13016: If you type an Emacs command you did not intend, the results are often ! 13017: mysterious. This chapter tells what you can do to cancel your mistake or ! 13018: recover from a mysterious situation. Emacs bugs and system crashes are ! 13019: also considered. ! 13020: @end iftex ! 13021: ! 13022: @node Quitting, Lossage, Customization, Top ! 13023: @section Quitting and Aborting ! 13024: @cindex quitting ! 13025: ! 13026: @table @kbd ! 13027: @item C-g ! 13028: Quit. Cancel running or partially typed command. ! 13029: @item C-] ! 13030: Abort innermost recursive editing level and cancel the command which ! 13031: invoked it (@code{abort-recursive-edit}). ! 13032: @item M-x top-level ! 13033: Abort all recursive editing levels that are currently executing. ! 13034: @item C-x u ! 13035: Cancel an already-executed command, usually (@code{undo}). ! 13036: @end table ! 13037: ! 13038: There are two ways of cancelling commands which are not finished ! 13039: executing: @dfn{quitting} with @kbd{C-g}, and @dfn{aborting} with @kbd{C-]} ! 13040: or @kbd{M-x top-level}. Quitting is cancelling a partially typed command ! 13041: or one which is already running. Aborting is getting out of a recursive ! 13042: editing level and cancelling the command that invoked the recursive edit. ! 13043: ! 13044: @cindex quitting ! 13045: @cindex C-g ! 13046: Quitting with @kbd{C-g} is used for getting rid of a partially typed ! 13047: command, or a numeric argument that you don't want. It also stops a ! 13048: running command in the middle in a relatively safe way, so you can use it ! 13049: if you accidentally give a command which takes a long time. In particular, ! 13050: it is safe to quit out of killing; either your text will @var{all} still be ! 13051: there, or it will @var{all} be in the kill ring (or maybe both). Quitting ! 13052: an incremental search does special things documented under searching; in ! 13053: general, it may take two successive @kbd{C-g} characters to get out of a ! 13054: search. @kbd{C-g} works by setting the variable @code{quit-flag} to ! 13055: @code{t} the instant @kbd{C-g} is typed; Emacs Lisp checks this variable ! 13056: frequently and quits if it is non-@code{nil}. @kbd{C-g} is only actually ! 13057: executed as a command if it is typed while Emacs is waiting for input. ! 13058: ! 13059: If you quit twice in a row before the first @kbd{C-g} is recognized, you ! 13060: activate the ``emergency escape'' feature and return to the shell. ! 13061: @xref{Emergency Escape}. ! 13062: ! 13063: @cindex recursive editing level ! 13064: @cindex editing level, recursive ! 13065: @cindex aborting ! 13066: @findex abort-recursive-edit ! 13067: @kindex C-] ! 13068: Aborting with @kbd{C-]} (@code{abort-recursive-edit}) is used to get out ! 13069: of a recursive editing level and cancel the command which invoked it. ! 13070: Quitting with @kbd{C-g} does not do this, and could not do this, because it ! 13071: is used to cancel a partially typed command @i{within} the recursive ! 13072: editing level. Both operations are useful. For example, if you are in the ! 13073: Emacs debugger (@pxref{Lisp Debug}) and have typed @kbd{C-u 8} to enter a ! 13074: numeric argument, you can cancel that argument with @kbd{C-g} and remain in ! 13075: the debugger. ! 13076: ! 13077: @findex top-level ! 13078: The command @kbd{M-x top-level} is equivalent to ``enough'' @kbd{C-]} ! 13079: commands to get you out of all the levels of recursive edits that you are ! 13080: in. @kbd{C-]} gets you out one level at a time, but @kbd{M-x top-level} ! 13081: goes out all levels at once. Both @kbd{C-]} and @kbd{M-x top-level} are ! 13082: like all other commands, and unlike @kbd{C-g}, in that they are effective ! 13083: only when Emacs is ready for a command. @kbd{C-]} is an ordinary key and ! 13084: has its meaning only because of its binding in the keymap. ! 13085: @xref{Recursive Edit}. ! 13086: ! 13087: @kbd{C-x u} (@code{undo}) is not strictly speaking a way of cancelling a ! 13088: command, but you can think of it as cancelling a command already finished ! 13089: executing. @xref{Undo}. ! 13090: ! 13091: @node Lossage, Bugs, Quitting, Top ! 13092: @section Dealing with Emacs Trouble ! 13093: ! 13094: This section describes various conditions in which Emacs fails to work, ! 13095: and how to recognize them and correct them. ! 13096: ! 13097: @menu ! 13098: * Stuck Recursive:: `[...]' in mode line around the parentheses ! 13099: * Screen Garbled:: Garbage on the screen ! 13100: * Text Garbled:: Garbage in the text ! 13101: * Unasked-for Search:: Spontaneous entry to incremental search ! 13102: * Emergency Escape:: Emergency escape--- ! 13103: What to do if Emacs stops responding ! 13104: * Total Frustration:: When you are at your wits' end. ! 13105: @end menu ! 13106: ! 13107: @node Stuck Recursive, Screen Garbled, Lossage, Lossage ! 13108: @subsection Recursive Editing Levels ! 13109: ! 13110: Recursive editing levels are important and useful features of Emacs, but ! 13111: they can seem like malfunctions to the user who does not understand them. ! 13112: ! 13113: If the mode line has square brackets @samp{[@dots{}]} around the parentheses ! 13114: that contain the names of the major and minor modes, you have entered a ! 13115: recursive editing level. If you did not do this on purpose, or if you ! 13116: don't understand what that means, you should just get out of the recursive ! 13117: editing level. To do so, type @kbd{M-x top-level}. This is called getting ! 13118: back to top level. @xref{Recursive Edit}. ! 13119: ! 13120: @node Screen Garbled, Text Garbled, Stuck Recursive, Lossage ! 13121: @subsection Garbage on the Screen ! 13122: ! 13123: If the data on the screen looks wrong, the first thing to do is see ! 13124: whether the text is really wrong. Type @kbd{C-l}, to redisplay the entire ! 13125: screen. If it appears correct after this, the problem was entirely in the ! 13126: previous screen update. ! 13127: ! 13128: Display updating problems often result from an incorrect termcap entry ! 13129: for the terminal you are using. The file @file{etc/TERMS} in the Emacs ! 13130: distribution gives the fixes for known problems of this sort. ! 13131: @file{INSTALL} contains general advice for these problems in one of its ! 13132: sections. Very likely there is simply insufficient padding for certain ! 13133: display operations. To investigate the possibility that you have this sort ! 13134: of problem, try Emacs on another terminal made by a different manufacturer. ! 13135: If problems happen frequently on one kind of terminal but not another kind, ! 13136: it is likely to be a bad termcap entry, though it could also be due to a ! 13137: bug in Emacs that appears for terminals that have or that lack specific ! 13138: features. ! 13139: ! 13140: @node Text Garbled, Unasked-for Search, Screen Garbled, Lossage ! 13141: @subsection Garbage in the Text ! 13142: ! 13143: If @kbd{C-l} shows that the text is wrong, try undoing the changes to it ! 13144: using @kbd{C-x u} until it gets back to a state you consider correct. Also ! 13145: try @kbd{C-h l} to find out what command you typed to produce the observed ! 13146: results. ! 13147: ! 13148: If a large portion of text appears to be missing at the beginning or ! 13149: end of the buffer, check for the word @samp{Narrow} in the mode line. ! 13150: If it appears, the text is still present, but marked off-limits. ! 13151: To make it visible again, type @kbd{C-x w}. @xref{Narrowing}. ! 13152: ! 13153: @node Unasked-for Search, Emergency Escape, Text Garbled, Lossage ! 13154: @subsection Spontaneous Entry to Incremental Search ! 13155: ! 13156: If Emacs spontaneously displays @samp{I-search:} at the bottom of the ! 13157: screen, it means that the terminal is sending @kbd{C-s} and @kbd{C-q} ! 13158: according to the poorly designed xon/xoff ``flow control'' protocol. You ! 13159: should try to prevent this by putting the terminal in a mode where it will ! 13160: not use flow control or giving it enough padding that it will never send a ! 13161: @kbd{C-s}. If that cannot be done, you must tell Emacs to expect flow ! 13162: control to be used, until you can get a properly designed terminal. ! 13163: ! 13164: Information on how to do these things can be found in the file ! 13165: @file{INSTALL} in the Emacs distribution. ! 13166: ! 13167: @node Emergency Escape, Total Frustration, Unasked-for Search, Lossage ! 13168: @subsection Emergency Escape ! 13169: ! 13170: Because at times there have been bugs causing Emacs to loop without ! 13171: checking @code{quit-flag}, a special feature causes Emacs to be suspended ! 13172: immediately if you type a second @kbd{C-g} while the flag is already set, ! 13173: so you can always get out of GNU Emacs. Normally Emacs recognizes and ! 13174: clears @code{quit-flag} (and quits!) quickly enough to prevent this from ! 13175: happening. ! 13176: ! 13177: When you resume Emacs after a suspension caused by multiple @kbd{C-g}, it ! 13178: asks two questions before going back to what it had been doing: ! 13179: ! 13180: @example ! 13181: Auto-save? (y or n) ! 13182: Abort (and dump core)? (y or n) ! 13183: @end example ! 13184: ! 13185: @noindent ! 13186: Answer each one with @kbd{y} or @kbd{n} followed by @key{RET}. ! 13187: ! 13188: Saying @kbd{y} to @samp{Auto-save?} causes immediate auto-saving of all ! 13189: modified buffers in which auto-saving is enabled. ! 13190: ! 13191: Saying @kbd{y} to @samp{Abort (and dump core)?} causes an illegal instruction to be ! 13192: executed, dumping core. This is to enable a wizard to figure out why Emacs ! 13193: was failing to quit in the first place. Execution does not continue ! 13194: after a core dump. If you answer @kbd{n}, execution does continue. With ! 13195: luck, GNU Emacs will ultimately check @code{quit-flag} and quit normally. ! 13196: If not, and you type another @kbd{C-g}, it is suspended again. ! 13197: ! 13198: If Emacs is not really hung, just slow, you may invoke the double ! 13199: @kbd{C-g} feature without really meaning to. Then just resume and answer ! 13200: @kbd{n} to both questions, and you will arrive at your former state. ! 13201: Presumably the quit you requested will happen soon. ! 13202: ! 13203: The double-@kbd{C-g} feature may be turned off when Emacs is running under ! 13204: a window system, since the window system always enables you to kill Emacs ! 13205: or to create another window and run another program. ! 13206: ! 13207: @node Total Frustration,, Emergency Escape, Lossage ! 13208: @subsection Help for Total Frustration ! 13209: @cindex Eliza ! 13210: @cindex doctor ! 13211: ! 13212: If using Emacs (or something else) becomes terribly frustrating and none ! 13213: of the techniques described above solve the problem, Emacs can still help ! 13214: you. ! 13215: ! 13216: First, if the Emacs you are using is not responding to commands, type ! 13217: @kbd{C-g C-g} to get out of it and then start a new one. ! 13218: ! 13219: @findex doctor ! 13220: Second, type @kbd{M-x doctor @key{RET}}. ! 13221: ! 13222: The doctor will make you feel better. Each time you say something to ! 13223: the doctor, you must end it by typing @key{RET} @key{RET}. This lets the ! 13224: doctor know you are finished. ! 13225: ! 13226: @node Bugs, Manifesto, Lossage, Top ! 13227: @section Reporting Bugs ! 13228: ! 13229: @cindex bugs ! 13230: Sometimes you will encounter a bug in Emacs. Although we cannot promise ! 13231: we can or will fix the bug, and we might not even agree that it is a bug, ! 13232: we want to hear about bugs you encounter in case we do want to fix them. ! 13233: ! 13234: To make it possible for us to fix a bug, you must report it. In order ! 13235: to do so effectively, you must know when and how to do it. ! 13236: ! 13237: @subsection When Is There a Bug ! 13238: ! 13239: If Emacs executes an illegal instruction, or dies with an operating ! 13240: system error message that indicates a problem in the program (as opposed to ! 13241: something like ``disk full''), then it is certainly a bug. ! 13242: ! 13243: If Emacs updates the display in a way that does not correspond to what is ! 13244: in the buffer, then it is certainly a bug. If a command seems to do the ! 13245: wrong thing but the problem corrects itself if you type @kbd{C-l}, it is a ! 13246: case of incorrect display updating. ! 13247: ! 13248: Taking forever to complete a command can be a bug, but you must make ! 13249: certain that it was really Emacs's fault. Some commands simply take a long ! 13250: time. Type @kbd{C-g} and then @kbd{C-h l} to see whether the input Emacs ! 13251: received was what you intended to type; if the input was such that you ! 13252: @var{know} it should have been processed quickly, report a bug. If you ! 13253: don't know whether the command should take a long time, find out by looking ! 13254: in the manual or by asking for assistance. ! 13255: ! 13256: If a command you are familiar with causes an Emacs error message in a ! 13257: case where its usual definition ought to be reasonable, it is probably a ! 13258: bug. ! 13259: ! 13260: If a command does the wrong thing, that is a bug. But be sure you know ! 13261: for certain what it ought to have done. If you aren't familiar with the ! 13262: command, or don't know for certain how the command is supposed to work, ! 13263: then it might actually be working right. Rather than jumping to ! 13264: conclusions, show the problem to someone who knows for certain. ! 13265: ! 13266: Finally, a command's intended definition may not be best for editing ! 13267: with. This is a very important sort of problem, but it is also a matter of ! 13268: judgment. Also, it is easy to come to such a conclusion out of ignorance ! 13269: of some of the existing features. It is probably best not to complain ! 13270: about such a problem until you have checked the documentation in the usual ! 13271: ways, feel confident that you understand it, and know for certain that what ! 13272: you want is not available. If you are not sure what the command is ! 13273: supposed to do after a careful reading of the manual, check the index and ! 13274: glossary for any terms that may be unclear. If you still do not ! 13275: understand, this indicates a bug in the manual. The manual's job is to ! 13276: make everything clear. It is just as important to report documentation ! 13277: bugs as program bugs. ! 13278: ! 13279: If the on-line documentation string of a function or variable disagrees ! 13280: with the manual, one of them must be wrong, so report the bug. ! 13281: ! 13282: @subsection How to Report a Bug ! 13283: ! 13284: @findex emacs-version ! 13285: When you decide that there is a bug, it is important to report it and to ! 13286: report it in a way which is useful. What is most useful is an exact ! 13287: description of what commands you type, starting with the shell command to ! 13288: run Emacs, until the problem happens. Always include the version number ! 13289: of Emacs that you are using; type @kbd{M-x emacs-version} to print this. ! 13290: ! 13291: The most important principle in reporting a bug is to report @var{facts}, ! 13292: not hypotheses or categorizations. It is always easier to report the facts, ! 13293: but people seem to prefer to strain to posit explanations and report ! 13294: them instead. If the explanations are based on guesses about how Emacs is ! 13295: implemented, they will be useless; we will have to try to figure out what ! 13296: the facts must have been to lead to such speculations. Sometimes this is ! 13297: impossible. But in any case, it is unnecessary work for us. ! 13298: ! 13299: For example, suppose that you type @kbd{C-x C-f /glorp/baz.ugh ! 13300: @key{RET}}, visiting a file which (you know) happens to be rather large, ! 13301: and Emacs prints out @samp{I feel pretty today}. The best way to report ! 13302: the bug is with a sentence like the preceding one, because it gives all the ! 13303: facts and nothing but the facts. ! 13304: ! 13305: Do not assume that the problem is due to the size of the file and say, ! 13306: ``When I visit a large file, Emacs prints out @samp{I feel pretty today}.'' ! 13307: This is what we mean by ``guessing explanations''. The problem is just as ! 13308: likely to be due to the fact that there is a @samp{z} in the file name. If ! 13309: this is so, then when we got your report, we would try out the problem with ! 13310: some ``large file'', probably with no @samp{z} in its name, and not find ! 13311: anything wrong. There is no way in the world that we could guess that we ! 13312: should try visiting a file with a @samp{z} in its name. ! 13313: ! 13314: Alternatively, the problem might be due to the fact that the file starts ! 13315: with exactly 25 spaces. For this reason, you should make sure that you ! 13316: inform us of the exact contents of any file that is needed to reproduce the ! 13317: bug. What if the problem only occurs when you have typed the @kbd{C-x C-a} ! 13318: command previously? This is why we ask you to give the exact sequence of ! 13319: characters you typed since starting to use Emacs. ! 13320: ! 13321: You should not even say ``visit a file'' instead of @kbd{C-x C-f} unless ! 13322: you @i{know} that it makes no difference which visiting command is used. ! 13323: Similarly, rather than saying ``if I have three characters on the line,'' ! 13324: say ``after I type @kbd{@key{RET} A B C @key{RET} C-p},'' if that is ! 13325: the way you entered the text.@refill ! 13326: ! 13327: If you are not in Fundamental mode when the problem occurs, you should ! 13328: say what mode you are in. ! 13329: ! 13330: If the manifestation of the bug is an Emacs error message, it is ! 13331: important to report not just the text of the error message but a backtrace ! 13332: showing how the Lisp program in Emacs arrived at the error. To make the ! 13333: backtrace, you must execute the Lisp expression ! 13334: @code{(setq @w{debug-on-error t})} before the error happens (that is to ! 13335: say, you must execute that expression and then make the bug happen). This ! 13336: causes the Lisp debugger to run (@pxref{Lisp Debug}). The debugger's ! 13337: backtrace can be copied as text into the bug report. This use of the ! 13338: debugger is possible only if you know how to make the bug happen again. Do ! 13339: note the error message the first time the bug happens, so if you can't make ! 13340: it happen again, you can report at least that. ! 13341: ! 13342: Check whether any programs you have loaded into the Lisp world, including ! 13343: your @file{.emacs} file, set any variables that may affect the functioning ! 13344: of Emacs. Also, see whether the problem happens in a freshly started Emacs ! 13345: without loading your @file{.emacs} file (start Emacs with the @code{-q} switch ! 13346: to prevent loading the init file.) If the problem does @var{not} occur ! 13347: then, it is essential that we know the contents of any programs that you ! 13348: must load into the Lisp world in order to cause the problem to occur. ! 13349: ! 13350: If the problem does depend on an init file or other Lisp programs that ! 13351: are not part of the standard Emacs system, then you should make sure it is ! 13352: not a bug in those programs by complaining to their maintainers first. ! 13353: After they verify that they are using Emacs in a way that is supposed to ! 13354: work, they should report the bug. ! 13355: ! 13356: If you can tell us a way to cause the problem without visiting any files, ! 13357: please do so. This makes it much easier to debug. If you do need files, ! 13358: make sure you arrange for us to see their exact contents. For example, it ! 13359: can often matter whether there are spaces at the ends of lines, or a ! 13360: newline after the last line in the buffer (nothing ought to care whether ! 13361: the last line is terminated, but tell that to the bugs). ! 13362: ! 13363: @findex open-dribble-file ! 13364: @cindex dribble file ! 13365: The easy way to record the input to Emacs precisely is to to write a ! 13366: dribble file; execute the Lisp expression ! 13367: ! 13368: @example ! 13369: (open-dribble-file "~/dribble") ! 13370: @end example ! 13371: ! 13372: @noindent ! 13373: using @kbd{Meta-@key{ESC}} or from the @samp{*scratch*} buffer just after starting ! 13374: Emacs. From then on, all Emacs input will be written in the specified ! 13375: dribble file until the Emacs process is killed. ! 13376: ! 13377: @findex open-termscript ! 13378: @cindex termscript file ! 13379: For possible display bugs, it is important to report the terminal type ! 13380: (the value of environment variable @code{TERM}), the complete termcap entry ! 13381: for the terminal from @file{/etc/termcap} (since that file is not identical ! 13382: on all machines), and the output that Emacs actually sent to the terminal. ! 13383: The way to collect this output is to execute the Lisp expression ! 13384: ! 13385: @example ! 13386: (open-termscript "~/termscript") ! 13387: @end example ! 13388: ! 13389: @noindent ! 13390: using @kbd{Meta-@key{ESC}} or from the @samp{*scratch*} buffer just ! 13391: after starting Emacs. From then on, all output from Emacs to the terminal ! 13392: will be written in the specified termscript file as well, until the Emacs ! 13393: process is killed. If the problem happens when Emacs starts up, put this ! 13394: expression into your @file{.emacs} file so that the termscript file will ! 13395: be open when Emacs displays the screen for the first time. Be warned: ! 13396: it is often difficult, and sometimes impossible, to fix a terminal-dependent ! 13397: bug without access to a terminal of the type that stimulates the bug.@refill ! 13398: ! 13399: The address for reporting bugs is ! 13400: ! 13401: @format ! 13402: GNU Emacs Bugs ! 13403: 545 Tech Sq, rm 703 ! 13404: Cambridge, MA 02139 ! 13405: @end format ! 13406: ! 13407: @noindent ! 13408: or send email to @samp{mit-eddie!bug-gnu-emacs} (Usenet) or ! 13409: @samp{bug-gnu-emacs@@prep.ai.mit.edu} (Internet). ! 13410: ! 13411: Once again, we do not promise to fix the bug; but if the bug is serious, ! 13412: or ugly, or easy to fix, chances are we will want to. ! 13413: ! 13414: @iftex ! 13415: @unnumbered Emacs Version 17 Antinews ! 13416: ! 13417: For those of you who are downgrading from version 18 to version 17 of GNU ! 13418: Emacs, here is a list of the old features. You will note many ! 13419: simplifications; complicated features have been eliminated. The list does ! 13420: not include changes affecting only topics not dealt with in this manual. ! 13421: ! 13422: @unnumberedsec General Changes ! 13423: ! 13424: @itemize @bullet ! 13425: @item ! 13426: Vi, EDT and Gosmacs emulation have been eliminated in version 17. The ! 13427: idea is that other editors are obsolete and nobody should want to ! 13428: remember they exist. ! 13429: ! 13430: @item ! 13431: The buffer-sorting commands of version 18 have been eliminated in version ! 13432: 17. @xref{Sorting}. ! 13433: ! 13434: @item ! 13435: The @kbd{M-@key{TAB}} command for completion of Lisp symbol names has ! 13436: been eliminated. ! 13437: ! 13438: @item ! 13439: The @kbd{M-/} command for dynamic abbrev expansion has been eliminated. ! 13440: ! 13441: @item ! 13442: @kbd{C-M-v} is no longer redefined in the minibuffer. It has its standard ! 13443: meaning, which is to scroll the ``next'' window. In the minibuffer, the ! 13444: ``next'' window is always the one at the top of the screen. @xref{Windows}. ! 13445: ! 13446: @item ! 13447: The old command @kbd{M-x occur-menu} is now the way to ask for a list ! 13448: of matches for a regexp and then pick one and move point to it. Refer ! 13449: to its on-line documentation for full details of its use. @kbd{M-x ! 13450: occur} has been simplified and now just displays a list of matches ! 13451: with no fancy options. @xref{Other Repeating Search}. ! 13452: ! 13453: @item ! 13454: Incremental searches both ordinary and regexp now share a single ! 13455: default search string which is the last thing searched for by either ! 13456: kind of incremental search. They do not wrap to the beginning or end ! 13457: of the buffer. @xref{Incremental Search}. ! 13458: ! 13459: @item ! 13460: The variables @code{search-low-speed} and @code{search-slow-window-lines} ! 13461: have been renamed to start with @code{isearch} instead of @code{search}. ! 13462: ! 13463: @item ! 13464: Undo in version 17 clears the ``modified'' flag more often. If the ! 13465: buffer contents that result from undoing are the same as at a prior ! 13466: instant when the ``modified'' flag was clear, the ``modified'' flag ! 13467: is cleared again. @xref{Undo}. ! 13468: ! 13469: @item ! 13470: @kbd{C-x C-v} is allowed only when the current buffer is visiting a ! 13471: file. @xref{Visiting}. ! 13472: ! 13473: @item ! 13474: Auto-save file names in version 17 do not have a final @samp{#}. The ! 13475: auto-save file name for a file @file{foo.c} is therefore @file{#foo.c}. ! 13476: @xref{Auto Save}. ! 13477: ! 13478: @item ! 13479: @kbd{M-x recover-file} works more simply. It does not compare the dates of ! 13480: the specified file and its auto-save file; it does not display a directory ! 13481: listing for them. You must figure out on your own whether you want to ! 13482: recover the file from its auto-save file. ! 13483: ! 13484: @item ! 13485: Some of the command line switches have been eliminated ! 13486: (@pxref{Command Switches}). Switches eliminated include ! 13487: @samp{-insert} and @samp{-i}, and the alternate names @samp{-funcall}, ! 13488: @samp{-load}, @samp{-user} and @samp{-no-init-file}.@refill ! 13489: @end itemize ! 13490: ! 13491: @unnumberedsec Changes in Major Modes ! 13492: ! 13493: @itemize @bullet ! 13494: @item ! 13495: Fortran mode has been eliminated. ! 13496: ! 13497: @item ! 13498: Nroff mode no longer defines a syntax for comments (@pxref{Nroff Mode}). ! 13499: ! 13500: @item ! 13501: The two kinds of @TeX{} mode have been combined into one; @kbd{M-x tex-mode} ! 13502: simply turns on this mode instead of choosing among two others. A further ! 13503: simplification is the elimination of the commands @kbd{C-c C-f}, ! 13504: @kbd{C-c C-k}, @kbd{C-c C-l} and @kbd{C-c C-q}. @xref{TeX Mode}.@refill ! 13505: ! 13506: @item ! 13507: All the special commands of Outline mode have been moved to new keys ! 13508: or eliminated (@pxref{Outline Mode}). ! 13509: ! 13510: @itemize @bullet ! 13511: @item ! 13512: @kbd{C-c C-n} becomes @kbd{M-@}}. ! 13513: @item ! 13514: @kbd{C-c C-p} becomes @kbd{M-@{}. ! 13515: @item ! 13516: @kbd{C-c C-f}, @kbd{C-c C-b} and @kbd{C-c C-u} are eliminated. ! 13517: @end itemize ! 13518: ! 13519: The variable @code{outline-regexp} has also been eliminated in version ! 13520: 17. ! 13521: ! 13522: @item ! 13523: In C mode, @key{TAB} always reindents the current line. The variable ! 13524: @code{c-tab-always-indent} has been eliminated and Emacs acts as if ! 13525: it were @code{t}. @xref{C Indent}. ! 13526: ! 13527: @item ! 13528: Linefeed is now redefined in C mode so that it reindents (with ! 13529: @key{TAB}) both of the lines that result from breaking the current ! 13530: line. ! 13531: ! 13532: @item ! 13533: The special commands used in Picture mode to specify the direction of ! 13534: cursor motion after self-inserting characters have been given new keys ! 13535: (@pxref{Picture}). They are now ! 13536: ! 13537: @itemize @bullet ! 13538: @item ! 13539: @kbd{M-`} to request leftward motion. ! 13540: @item ! 13541: @kbd{M-'} to request rightward motion. ! 13542: @item ! 13543: @kbd{M--} to request upward motion. ! 13544: @item ! 13545: @kbd{M-=} to request downward motion. ! 13546: @item ! 13547: @kbd{C-c `} to request upward and leftward motion. ! 13548: @item ! 13549: @kbd{C-c '} to request upward and rightward motion. ! 13550: @item ! 13551: @kbd{C-c /} to request downward and leftward motion. ! 13552: @item ! 13553: @kbd{C-c \} to request downward and rightward motion. ! 13554: @end itemize ! 13555: ! 13556: @item ! 13557: The special @kbd{C-c} commands of Mail mode have been given new keys ! 13558: (@pxref{Sending Mail}). ! 13559: ! 13560: @itemize @bullet ! 13561: @item ! 13562: @kbd{C-c C-f C-s} becomes @kbd{C-c s} ! 13563: @item ! 13564: @kbd{C-c C-f C-t} becomes @kbd{C-c t} ! 13565: @item ! 13566: @kbd{C-c C-f C-b} becomes @kbd{C-c b} ! 13567: @item ! 13568: @kbd{C-c C-f C-c} becomes @kbd{C-c c} ! 13569: @item ! 13570: @kbd{C-c C-y} becomes @kbd{C-c y} ! 13571: @item ! 13572: @kbd{C-c C-q} becomes @kbd{C-c q} ! 13573: @item ! 13574: @kbd{C-c C-w} becomes @kbd{C-c w} ! 13575: @end itemize ! 13576: ! 13577: @item ! 13578: The @kbd{g} command in Dired has been removed (@pxref{Dired}). ! 13579: @end itemize ! 13580: ! 13581: @unnumberedsec Init Files and Library Changes ! 13582: ! 13583: @itemize @bullet ! 13584: @item ! 13585: The commands @code{load-file} and @code{load-library} are replaced ! 13586: with one command, @code{load}. This command is logically the same as ! 13587: version 18 @code{load-library}, but due to changes in the order of ! 13588: searching it can also serve in place of @code{load-file}. ! 13589: @xref{Loading}. ! 13590: ! 13591: The search order in version 17 is: ! 13592: @enumerate ! 13593: @item ! 13594: Search all the directories in the search path for the file name as given. ! 13595: @item ! 13596: Append the suffix @samp{.elc} and search all the directories. ! 13597: @item ! 13598: Remove the final @samp{c}, resulting in a suffix @samp{.el}, and search ! 13599: all the directories. ! 13600: @end enumerate ! 13601: ! 13602: The search path in version 17 normally starts with @code{nil}, meaning ! 13603: the current default directory. ! 13604: ! 13605: As a result, the first file name that @code{load} tries is the one ! 13606: @code{load-file} would use in version 18: no suffix, and current ! 13607: default directory. ! 13608: ! 13609: @item ! 13610: The default init file is called @file{default-profile} instead of ! 13611: @file{default.el} or @file{default.elc}. Also, it is executed ! 13612: only if you have no init file of your own. ! 13613: ! 13614: @item ! 13615: The terminal-independent keypad support in the @file{keypad} library ! 13616: has been eliminated. @xref{Terminal Init}. ! 13617: ! 13618: @item ! 13619: The function @code{setq-default} has been eliminated. Use ! 13620: @code{set-default} and quote the variable name, as in ! 13621: ! 13622: @example ! 13623: (set-default '@var{variable} @var{value}) ! 13624: @end example ! 13625: ! 13626: Several built-in variables now are always local to all buffers. ! 13627: ! 13628: These variables are @code{tab-width}, @code{ctl-arrow}, ! 13629: @code{truncate-lines}, @code{fill-column}, @code{left-margin}, ! 13630: @code{mode-line-format}, @code{abbrev-mode}, @code{overwrite-mode}, ! 13631: @code{case-fold-search}, @code{auto-fill-hook}, ! 13632: @code{selective-display}.@refill ! 13633: ! 13634: @code{set-default} does not work with these variables. They do have ! 13635: defaults, but the defaults affect only buffers yet to be created. The ! 13636: only way to set the default for variable @var{foo} is to set the ! 13637: variable named @code{default-@var{foo}}, such as ! 13638: @code{default-case-fold-search} and @code{default-fill-column}.@refill ! 13639: ! 13640: @item ! 13641: Some variables have been eliminated. Emacs version 17 always behaves ! 13642: as if they were @code{nil}. ! 13643: ! 13644: @itemize @bullet ! 13645: @item ! 13646: @code{backup-by-copying-when-mismatch} ! 13647: @item ! 13648: @code{find-file-hooks} ! 13649: @item ! 13650: @code{find-file-not-found-hooks} ! 13651: @item ! 13652: @code{write-file-hooks} ! 13653: @item ! 13654: @code{file-precious-flag} ! 13655: @item ! 13656: @code{no-redraw-on-reenter} ! 13657: @end itemize ! 13658: @end itemize ! 13659: ! 13660: @end iftex ! 13661: ! 13662: @node Manifesto,, Bugs, Top ! 13663: @unnumbered The GNU Manifesto ! 13664: ! 13665: @unnumberedsec What's GNU? Gnu's Not Unix! ! 13666: ! 13667: GNU, which stands for Gnu's Not Unix, is the name for the complete ! 13668: Unix-compatible software system which I am writing so that I can give it ! 13669: away free to everyone who can use it. Several other volunteers are helping ! 13670: me. Contributions of time, money, programs and equipment are greatly ! 13671: needed. ! 13672: ! 13673: So far we have an Emacs text editor with Lisp for writing editor commands, ! 13674: a source level debugger, a yacc-compatible parser generator, a linker, and ! 13675: around 35 utilities. A shell (command interpreter) is nearly completed. A ! 13676: new portable optimizing C compiler has compiled itself and may be released ! 13677: this year. An initial kernel exists but many more features are needed to ! 13678: emulate Unix. When the kernel and compiler are finished, it will be ! 13679: possible to distribute a GNU system suitable for program development. We ! 13680: will use @TeX{} as our text formatter, but an nroff is being worked on. We ! 13681: will use the free, portable X window system as well. After this we will ! 13682: add a portable Common Lisp, an Empire game, a spreadsheet, and hundreds of ! 13683: other things, plus on-line documentation. We hope to supply, eventually, ! 13684: everything useful that normally comes with a Unix system, and more. ! 13685: ! 13686: GNU will be able to run Unix programs, but will not be identical to Unix. ! 13687: We will make all improvements that are convenient, based on our experience ! 13688: with other operating systems. In particular, we plan to have longer ! 13689: filenames, file version numbers, a crashproof file system, filename ! 13690: completion perhaps, terminal-independent display support, and perhaps ! 13691: eventually a Lisp-based window system through which several Lisp programs ! 13692: and ordinary Unix programs can share a screen. Both C and Lisp will be ! 13693: available as system programming languages. We will try to support UUCP, ! 13694: MIT Chaosnet, and Internet protocols for communication. ! 13695: ! 13696: GNU is aimed initially at machines in the 68000/16000 class with virtual ! 13697: memory, because they are the easiest machines to make it run on. The extra ! 13698: effort to make it run on smaller machines will be left to someone who wants ! 13699: to use it on them. ! 13700: ! 13701: To avoid horrible confusion, please pronounce the `G' in the word `GNU' ! 13702: when it is the name of this project. ! 13703: ! 13704: @unnumberedsec Why I Must Write GNU ! 13705: ! 13706: I consider that the golden rule requires that if I like a program I must ! 13707: share it with other people who like it. Software sellers want to divide ! 13708: the users and conquer them, making each user agree not to share with ! 13709: others. I refuse to break solidarity with other users in this way. I ! 13710: cannot in good conscience sign a nondisclosure agreement or a software ! 13711: license agreement. For years I worked within the Artificial Intelligence ! 13712: Lab to resist such tendencies and other inhospitalities, but eventually ! 13713: they had gone too far: I could not remain in an institution where such ! 13714: things are done for me against my will. ! 13715: ! 13716: So that I can continue to use computers without dishonor, I have decided to ! 13717: put together a sufficient body of free software so that I will be able to ! 13718: get along without any software that is not free. I have resigned from the ! 13719: AI lab to deny MIT any legal excuse to prevent me from giving GNU away. ! 13720: ! 13721: @unnumberedsec Why GNU Will Be Compatible with Unix ! 13722: ! 13723: Unix is not my ideal system, but it is not too bad. The essential features ! 13724: of Unix seem to be good ones, and I think I can fill in what Unix lacks ! 13725: without spoiling them. And a system compatible with Unix would be ! 13726: convenient for many other people to adopt. ! 13727: ! 13728: @unnumberedsec How GNU Will Be Available ! 13729: ! 13730: GNU is not in the public domain. Everyone will be permitted to modify and ! 13731: redistribute GNU, but no distributor will be allowed to restrict its ! 13732: further redistribution. That is to say, proprietary modifications will not ! 13733: be allowed. I want to make sure that all versions of GNU remain free. ! 13734: ! 13735: @unnumberedsec Why Many Other Programmers Want to Help ! 13736: ! 13737: I have found many other programmers who are excited about GNU and want to ! 13738: help. ! 13739: ! 13740: Many programmers are unhappy about the commercialization of system ! 13741: software. It may enable them to make more money, but it requires them to ! 13742: feel in conflict with other programmers in general rather than feel as ! 13743: comrades. The fundamental act of friendship among programmers is the ! 13744: sharing of programs; marketing arrangements now typically used essentially ! 13745: forbid programmers to treat others as friends. The purchaser of software ! 13746: must choose between friendship and obeying the law. Naturally, many decide ! 13747: that friendship is more important. But those who believe in law often do ! 13748: not feel at ease with either choice. They become cynical and think that ! 13749: programming is just a way of making money. ! 13750: ! 13751: By working on and using GNU rather than proprietary programs, we can be ! 13752: hospitable to everyone and obey the law. In addition, GNU serves as an ! 13753: example to inspire and a banner to rally others to join us in sharing. ! 13754: This can give us a feeling of harmony which is impossible if we use ! 13755: software that is not free. For about half the programmers I talk to, this ! 13756: is an important happiness that money cannot replace. ! 13757: ! 13758: @unnumberedsec How You Can Contribute ! 13759: ! 13760: I am asking computer manufacturers for donations of machines and money. ! 13761: I'm asking individuals for donations of programs and work. ! 13762: ! 13763: One consequence you can expect if you donate machines is that GNU will run ! 13764: on them at an early date. The machines should be complete, ready to use ! 13765: systems, approved for use in a residential area, and not in need of ! 13766: sophisticated cooling or power. ! 13767: ! 13768: I have found very many programmers eager to contribute part-time work for ! 13769: GNU. For most projects, such part-time distributed work would be very hard ! 13770: to coordinate; the independently-written parts would not work together. ! 13771: But for the particular task of replacing Unix, this problem is absent. A ! 13772: complete Unix system contains hundreds of utility programs, each of which ! 13773: is documented separately. Most interface specifications are fixed by Unix ! 13774: compatibility. If each contributor can write a compatible replacement for ! 13775: a single Unix utility, and make it work properly in place of the original ! 13776: on a Unix system, then these utilities will work right when put together. ! 13777: Even allowing for Murphy to create a few unexpected problems, assembling ! 13778: these components will be a feasible task. (The kernel will require closer ! 13779: communication and will be worked on by a small, tight group.) ! 13780: ! 13781: If I get donations of money, I may be able to hire a few people full or ! 13782: part time. The salary won't be high by programmers' standards, but I'm ! 13783: looking for people for whom building community spirit is as important as ! 13784: making money. I view this as a way of enabling dedicated people to devote ! 13785: their full energies to working on GNU by sparing them the need to make a ! 13786: living in another way. ! 13787: ! 13788: @unnumberedsec Why All Computer Users Will Benefit ! 13789: ! 13790: Once GNU is written, everyone will be able to obtain good system software ! 13791: free, just like air. ! 13792: ! 13793: This means much more than just saving everyone the price of a Unix license. ! 13794: It means that much wasteful duplication of system programming effort will ! 13795: be avoided. This effort can go instead into advancing the state of the ! 13796: art. ! 13797: ! 13798: Complete system sources will be available to everyone. As a result, a user ! 13799: who needs changes in the system will always be free to make them himself, ! 13800: or hire any available programmer or company to make them for him. Users ! 13801: will no longer be at the mercy of one programmer or company which owns the ! 13802: sources and is in sole position to make changes. ! 13803: ! 13804: Schools will be able to provide a much more educational environment by ! 13805: encouraging all students to study and improve the system code. Harvard's ! 13806: computer lab used to have the policy that no program could be installed on ! 13807: the system if its sources were not on public display, and upheld it by ! 13808: actually refusing to install certain programs. I was very much inspired by ! 13809: this. ! 13810: ! 13811: Finally, the overhead of considering who owns the system software and what ! 13812: one is or is not entitled to do with it will be lifted. ! 13813: ! 13814: Arrangements to make people pay for using a program, including licensing of ! 13815: copies, always incur a tremendous cost to society through the cumbersome ! 13816: mechanisms necessary to figure out how much (that is, which programs) a ! 13817: person must pay for. And only a police state can force everyone to obey ! 13818: them. Consider a space station where air must be manufactured at great ! 13819: cost: charging each breather per liter of air may be fair, but wearing the ! 13820: metered gas mask all day and all night is intolerable even if everyone can ! 13821: afford to pay the air bill. And the TV cameras everywhere to see if you ! 13822: ever take the mask off are outrageous. It's better to support the air ! 13823: plant with a head tax and chuck the masks. ! 13824: ! 13825: Copying all or parts of a program is as natural to a programmer as ! 13826: breathing, and as productive. It ought to be as free. ! 13827: ! 13828: @unnumberedsec Some Easily Rebutted Objections to GNU's Goals ! 13829: ! 13830: @quotation ! 13831: ``Nobody will use it if it is free, because that means they can't rely ! 13832: on any support.'' ! 13833: ! 13834: ``You have to charge for the program to pay for providing the ! 13835: support.'' ! 13836: @end quotation ! 13837: ! 13838: If people would rather pay for GNU plus service than get GNU free without ! 13839: service, a company to provide just service to people who have obtained GNU ! 13840: free ought to be profitable. ! 13841: ! 13842: We must distinguish between support in the form of real programming work ! 13843: and mere handholding. The former is something one cannot rely on from a ! 13844: software vendor. If your problem is not shared by enough people, the ! 13845: vendor will tell you to get lost. ! 13846: ! 13847: If your business needs to be able to rely on support, the only way is to ! 13848: have all the necessary sources and tools. Then you can hire any available ! 13849: person to fix your problem; you are not at the mercy of any individual. ! 13850: With Unix, the price of sources puts this out of consideration for most ! 13851: businesses. With GNU this will be easy. It is still possible for there to ! 13852: be no available competent person, but this problem cannot be blamed on ! 13853: distibution arrangements. GNU does not eliminate all the world's problems, ! 13854: only some of them. ! 13855: ! 13856: Meanwhile, the users who know nothing about computers need handholding: ! 13857: doing things for them which they could easily do themselves but don't know ! 13858: how. ! 13859: ! 13860: Such services could be provided by companies that sell just hand-holding ! 13861: and repair service. If it is true that users would rather spend money and ! 13862: get a product with service, they will also be willing to buy the service ! 13863: having got the product free. The service companies will compete in quality ! 13864: and price; users will not be tied to any particular one. Meanwhile, those ! 13865: of us who don't need the service should be able to use the program without ! 13866: paying for the service. ! 13867: ! 13868: @quotation ! 13869: ``You cannot reach many people without advertising, ! 13870: and you must charge for the program to support that.'' ! 13871: ! 13872: ``It's no use advertising a program people can get free.'' ! 13873: @end quotation ! 13874: ! 13875: There are various forms of free or very cheap publicity that can be used to ! 13876: inform numbers of computer users about something like GNU. But it may be ! 13877: true that one can reach more microcomputer users with advertising. If this ! 13878: is really so, a business which advertises the service of copying and ! 13879: mailing GNU for a fee ought to be successful enough to pay for its ! 13880: advertising and more. This way, only the users who benefit from the ! 13881: advertising pay for it. ! 13882: ! 13883: On the other hand, if many people get GNU from their friends, and such ! 13884: companies don't succeed, this will show that advertising was not really ! 13885: necessary to spread GNU. Why is it that free market advocates don't want ! 13886: to let the free market decide this? ! 13887: ! 13888: @quotation ! 13889: ``My company needs a proprietary operating system ! 13890: to get a competitive edge.'' ! 13891: @end quotation ! 13892: ! 13893: GNU will remove operating system software from the realm of competition. ! 13894: You will not be able to get an edge in this area, but neither will your ! 13895: competitors be able to get an edge over you. You and they will compete in ! 13896: other areas, while benefitting mutually in this one. If your business is ! 13897: selling an operating system, you will not like GNU, but that's tough on ! 13898: you. If your business is something else, GNU can save you from being ! 13899: pushed into the expensive business of selling operating systems. ! 13900: ! 13901: I would like to see GNU development supported by gifts from many ! 13902: manufacturers and users, reducing the cost to each. ! 13903: ! 13904: @quotation ! 13905: ``Don't programmers deserve a reward for their creativity?'' ! 13906: @end quotation ! 13907: ! 13908: If anything deserves a reward, it is social contribution. Creativity can ! 13909: be a social contribution, but only in so far as society is free to use the ! 13910: results. If programmers deserve to be rewarded for creating innovative ! 13911: programs, by the same token they deserve to be punished if they restrict ! 13912: the use of these programs. ! 13913: ! 13914: @quotation ! 13915: ``Shouldn't a programmer be able to ask for a reward for his creativity?'' ! 13916: @end quotation ! 13917: ! 13918: There is nothing wrong with wanting pay for work, or seeking to maximize ! 13919: one's income, as long as one does not use means that are destructive. But ! 13920: the means customary in the field of software today are based on ! 13921: destruction. ! 13922: ! 13923: Extracting money from users of a program by restricting their use of it is ! 13924: destructive because the restrictions reduce the amount and the ways that ! 13925: the program can be used. This reduces the amount of wealth that humanity ! 13926: derives from the program. When there is a deliberate choice to restrict, ! 13927: the harmful consequences are deliberate destruction. ! 13928: ! 13929: The reason a good citizen does not use such destructive means to become ! 13930: wealthier is that, if everyone did so, we would all become poorer from the ! 13931: mutual destructiveness. This is Kantian ethics; or, the Golden Rule. ! 13932: Since I do not like the consequences that result if everyone hoards ! 13933: information, I am required to consider it wrong for one to do so. ! 13934: Specifically, the desire to be rewarded for one's creativity does not ! 13935: justify depriving the world in general of all or part of that creativity. ! 13936: ! 13937: @quotation ! 13938: ``Won't programmers starve?'' ! 13939: @end quotation ! 13940: ! 13941: I could answer that nobody is forced to be a programmer. Most of us cannot ! 13942: manage to get any money for standing on the street and making faces. But ! 13943: we are not, as a result, condemned to spend our lives standing on the ! 13944: street making faces, and starving. We do something else. ! 13945: ! 13946: But that is the wrong answer because it accepts the questioner's implicit ! 13947: assumption: that without ownership of software, programmers cannot possibly ! 13948: be paid a cent. Supposedly it is all or nothing. ! 13949: ! 13950: The real reason programmers will not starve is that it will still be ! 13951: possible for them to get paid for programming; just not paid as much as ! 13952: now. ! 13953: ! 13954: Restricting copying is not the only basis for business in software. It is ! 13955: the most common basis because it brings in the most money. If it were ! 13956: prohibited, or rejected by the customer, software business would move to ! 13957: other bases of organization which are now used less often. There are ! 13958: always numerous ways to organize any kind of business. ! 13959: ! 13960: Probably programming will not be as lucrative on the new basis as it is ! 13961: now. But that is not an argument against the change. It is not considered ! 13962: an injustice that sales clerks make the salaries that they now do. If ! 13963: programmers made the same, that would not be an injustice either. (In ! 13964: practice they would still make considerably more than that.) ! 13965: ! 13966: @quotation ! 13967: ``Don't people have a right to control how their creativity is used?'' ! 13968: @end quotation ! 13969: ! 13970: ``Control over the use of one's ideas'' really constitutes control over ! 13971: other people's lives; and it is usually used to make their lives more ! 13972: difficult. ! 13973: ! 13974: People who have studied the issue of intellectual property rights carefully ! 13975: (such as lawyers) say that there is no intrinsic right to intellectual ! 13976: property. The kinds of supposed intellectual property rights that the ! 13977: government recognizes were created by specific acts of legislation for ! 13978: specific purposes. ! 13979: ! 13980: For example, the patent system was established to encourage inventors to ! 13981: disclose the details of their inventions. Its purpose was to help society ! 13982: rather than to help inventors. At the time, the life span of 17 years for ! 13983: a patent was short compared with the rate of advance of the state of the ! 13984: art. Since patents are an issue only among manufacturers, for whom the ! 13985: cost and effort of a license agreement are small compared with setting up ! 13986: production, the patents often do not do much harm. They do not obstruct ! 13987: most individuals who use patented products. ! 13988: ! 13989: The idea of copyright did not exist in ancient times, when authors ! 13990: frequently copied other authors at length in works of non-fiction. This ! 13991: practice was useful, and is the only way many authors' works have survived ! 13992: even in part. The copyright system was created expressly for the purpose ! 13993: of encouraging authorship. In the domain for which it was ! 13994: invented---books, which could be copied economically only on a printing ! 13995: press---it did little harm, and did not obstruct most of the individuals ! 13996: who read the books. ! 13997: ! 13998: All intellectual property rights are just licenses granted by society ! 13999: because it was thought, rightly or wrongly, that society as a whole would ! 14000: benefit by granting them. But in any particular situation, we have to ask: ! 14001: are we really better off granting such license? What kind of act are we ! 14002: licensing a person to do? ! 14003: ! 14004: The case of programs today is very different from that of books a hundred ! 14005: years ago. The fact that the easiest way to copy a program is from one ! 14006: neighbor to another, the fact that a program has both source code and ! 14007: object code which are distinct, and the fact that a program is used rather ! 14008: than read and enjoyed, combine to create a situation in which a person who ! 14009: enforces a copyright is harming society as a whole both materially and ! 14010: spiritually; in which a person should not do so regardless of whether the ! 14011: law enables him to. ! 14012: ! 14013: @quotation ! 14014: ``Competition makes things get done better.'' ! 14015: @end quotation ! 14016: ! 14017: The paradigm of competition is a race: by rewarding the winner, we ! 14018: encourage everyone to run faster. When capitalism really works this way, ! 14019: it does a good job; but its defenders are wrong in assuming it always works ! 14020: this way. If the runners forget why the reward is offered and become ! 14021: intent on winning, no matter how, they may find other strategies---such as, ! 14022: attacking other runners. If the runners get into a fist fight, they will ! 14023: all finish late. ! 14024: ! 14025: Proprietary and secret software is the moral equivalent of runners in a ! 14026: fist fight. Sad to say, the only referee we've got does not seem to ! 14027: object to fights; he just regulates them (``For every ten yards you run, ! 14028: you can fire one shot''). He really ought to break them up, and penalize ! 14029: runners for even trying to fight. ! 14030: ! 14031: @quotation ! 14032: ``Won't everyone stop programming without a monetary incentive?'' ! 14033: @end quotation ! 14034: ! 14035: Actually, many people will program with absolutely no monetary incentive. ! 14036: Programming has an irresistible fascination for some people, usually the ! 14037: people who are best at it. There is no shortage of professional musicians ! 14038: who keep at it even though they have no hope of making a living that way. ! 14039: ! 14040: But really this question, though commonly asked, is not appropriate to the ! 14041: situation. Pay for programmers will not disappear, only become less. So ! 14042: the right question is, will anyone program with a reduced monetary ! 14043: incentive? My experience shows that they will. ! 14044: ! 14045: For more than ten years, many of the world's best programmers worked at the ! 14046: Artificial Intelligence Lab for far less money than they could have had ! 14047: anywhere else. They got many kinds of non-monetary rewards: fame and ! 14048: appreciation, for example. And creativity is also fun, a reward in itself. ! 14049: ! 14050: Then most of them left when offered a chance to do the same interesting ! 14051: work for a lot of money. ! 14052: ! 14053: What the facts show is that people will program for reasons other than ! 14054: riches; but if given a chance to make a lot of money as well, they will ! 14055: come to expect and demand it. Low-paying organizations do poorly in ! 14056: competition with high-paying ones, but they do not have to do badly if the ! 14057: high-paying ones are banned. ! 14058: ! 14059: @quotation ! 14060: ``We need the programmers desperately. If they demand that we ! 14061: stop helping our neighbors, we have to obey.'' ! 14062: @end quotation ! 14063: ! 14064: You're never so desperate that you have to obey this sort of demand. ! 14065: Remember: millions for defense, but not a cent for tribute! ! 14066: ! 14067: @quotation ! 14068: ``Programmers need to make a living somehow.'' ! 14069: @end quotation ! 14070: ! 14071: In the short run, this is true. However, there are plenty of ways that ! 14072: programmers could make a living without selling the right to use a program. ! 14073: This way is customary now because it brings programmers and businessmen the ! 14074: most money, not because it is the only way to make a living. It is easy to ! 14075: find other ways if you want to find them. Here are a number of examples. ! 14076: ! 14077: A manufacturer introducing a new computer will pay for the porting of ! 14078: operating systems onto the new hardware. ! 14079: ! 14080: The sale of teaching, hand-holding and maintenance services could also ! 14081: employ programmers. ! 14082: ! 14083: People with new ideas could distribute programs as freeware, asking for ! 14084: donations from satisfied users, or selling hand-holding services. I have ! 14085: met people who are already working this way successfully. ! 14086: ! 14087: Users with related needs can form users' groups, and pay dues. A group ! 14088: would contract with programming companies to write programs that the ! 14089: group's members would like to use. ! 14090: ! 14091: All sorts of development can be funded with a Software Tax: ! 14092: ! 14093: @quotation ! 14094: Suppose everyone who buys a computer has to pay x percent of ! 14095: the price as a software tax. The government gives this to ! 14096: an agency like the NSF to spend on software development. ! 14097: ! 14098: But if the computer buyer makes a donation to software development ! 14099: himself, he can take a credit against the tax. He can donate to ! 14100: the project of his own choosing---often, chosen because he hopes to ! 14101: use the results when it is done. He can take a credit for any amount ! 14102: of donation up to the total tax he had to pay. ! 14103: ! 14104: The total tax rate could be decided by a vote of the payers of ! 14105: the tax, weighted according to the amount they will be taxed on. ! 14106: ! 14107: The consequences: ! 14108: ! 14109: @itemize @bullet ! 14110: @item ! 14111: The computer-using community supports software development. ! 14112: @item ! 14113: This community decides what level of support is needed. ! 14114: @item ! 14115: Users who care which projects their share is spent on ! 14116: can choose this for themselves. ! 14117: @end itemize ! 14118: @end quotation ! 14119: ! 14120: In the long run, making programs free is a step toward the post-scarcity ! 14121: world, where nobody will have to work very hard just to make a living. ! 14122: People will be free to devote themselves to activities that are fun, such ! 14123: as programming, after spending the necessary ten hours a week on required ! 14124: tasks such as legislation, family counseling, robot repair and asteroid ! 14125: prospecting. There will be no need to be able to make a living from ! 14126: programming. ! 14127: ! 14128: We have already greatly reduced the amount of work that the whole society ! 14129: must do for its actual productivity, but only a little of this has ! 14130: translated itself into leisure for workers because much nonproductive ! 14131: activity is required to accompany productive activity. The main causes of ! 14132: this are bureaucracy and isometric struggles against competition. Free ! 14133: software will greatly reduce these drains in the area of software ! 14134: production. We must do this, in order for technical gains in productivity ! 14135: to translate into less work for us. ! 14136: ! 14137: @node Glossary, Key Index, Intro, Top ! 14138: @unnumbered Glossary ! 14139: ! 14140: @table @asis ! 14141: @item Abbrev ! 14142: An abbrev is a text string which expands into a different text string ! 14143: when present in the buffer. For example, you might define a short ! 14144: word as an abbrev for a long phrase that you want to insert ! 14145: frequently. @xref{Abbrevs}. ! 14146: ! 14147: @item Aborting ! 14148: Aborting means getting out of a recursive edit (q.v.@:). The ! 14149: commands @kbd{C-]} and @kbd{M-x top-level} are used for this. ! 14150: @xref{Quitting}. ! 14151: ! 14152: @item Auto Fill mode ! 14153: Auto Fill mode is a minor mode in which text that you insert is ! 14154: automatically broken into lines of fixed width. @xref{Filling}. ! 14155: ! 14156: @item Auto Saving ! 14157: Auto saving is when Emacs automatically stores the contents of an ! 14158: Emacs buffer in a specially-named file so that the information will ! 14159: not be lost if the buffer is lost due to a system error or user error. ! 14160: @xref{Auto Save}. ! 14161: ! 14162: @item Backup File ! 14163: A backup file records the contents that a file had before the current ! 14164: editing session. Emacs makes backup files automatically to help you ! 14165: track down or cancel changes you later regret making. @xref{Backup}. ! 14166: ! 14167: @item Balance Parentheses ! 14168: Emacs can balance parentheses manually or automatically. Manual ! 14169: balancing is done by the commands to move over balanced expressions ! 14170: (@pxref{Lists}). Automatic balancing is done by blinking the ! 14171: parenthesis that matches one just inserted (@pxref{Matching,,Matching ! 14172: Parens}). ! 14173: ! 14174: @item Bind ! 14175: To bind a key is to change its binding (q.v.@:). @xref{Rebinding}. ! 14176: ! 14177: @item Binding ! 14178: A key gets its meaning in Emacs by having a binding which is a ! 14179: command (q.v.@:), a Lisp function that is run when the key is typed. ! 14180: @xref{Commands,Binding}. Customization often involves rebinding a ! 14181: character to a different command function. The bindings of all keys ! 14182: are recorded in the keymaps (q.v.@:). @xref{Keymaps}. ! 14183: ! 14184: @item Blank Lines ! 14185: Blank lines are lines that contain only whitespace. Emacs has several ! 14186: commands for operating on the blank lines in the buffer. ! 14187: ! 14188: @item Buffer ! 14189: The buffer is the basic editing unit; one buffer corresponds to one ! 14190: piece of text being edited. You can have several buffers, but at any ! 14191: time you are editing only one, the `selected' buffer, though several ! 14192: can be visible when you are using multiple windows. @xref{Buffers}. ! 14193: ! 14194: @item Buffer Selection History ! 14195: Emacs keeps a buffer selection history which records how recently each ! 14196: Emacs buffer has been selected. This is used for choosing a buffer to ! 14197: select. @xref{Buffers}. ! 14198: ! 14199: @item C- ! 14200: @samp{C} in the name of a character is an abbreviation for Control. ! 14201: @xref{Characters,C-}. ! 14202: ! 14203: @item C-M- ! 14204: @samp{C-M-} in the name of a character is an abbreviation for ! 14205: Control-Meta. @xref{Characters,C-M-}. ! 14206: ! 14207: @item Case Conversion ! 14208: Case conversion means changing text from upper case to lower case or ! 14209: vice versa. @xref{Case}, for the commands for case conversion. ! 14210: ! 14211: @item Characters ! 14212: Characters form the contents of an Emacs buffer; also, Emacs commands ! 14213: are invoked by keys (q.v.@:), which are sequences of one or more ! 14214: characters. @xref{Characters}. ! 14215: ! 14216: @item Command ! 14217: A command is a Lisp function specially defined to be able to serve as ! 14218: a key binding in Emacs. When you type a key (q.v.@:), its binding ! 14219: (q.v.@:) is looked up in the relevant keymaps (q.v.@:) to find the ! 14220: command to run. @xref{Commands}. ! 14221: ! 14222: @item Command Name ! 14223: A command name is the name of a Lisp symbol which is a command ! 14224: (@pxref{Commands}). You can invoke any command by its name using ! 14225: @kbd{M-x} (@pxref{M-x}). ! 14226: ! 14227: @item Comments ! 14228: A comment is text in a program which is intended only for humans ! 14229: reading the program, and is marked specially so that it will be ! 14230: ignored when the program is loaded or compiled. Emacs offers special ! 14231: commands for creating, aligning and killing comments. ! 14232: @xref{Comments}. ! 14233: ! 14234: @item Compilation ! 14235: Compilation is the process of creating an executable program from ! 14236: source code. Emacs has commands for compiling files of Emacs Lisp ! 14237: code (@pxref{Lisp Libraries}) and programs in C and other languages ! 14238: (@pxref{Compilation}). ! 14239: ! 14240: @item Complete Key ! 14241: A complete key is a character or sequence of characters which, when typed ! 14242: by the user, fully specifies one action to be performed by Emacs. For ! 14243: example, @kbd{X} and @kbd{Control-f} and @kbd{Control-x m} are keys. Keys ! 14244: derive their meanings from being bound (q.v.@:) to commands (q.v.@:). ! 14245: Thus, @kbd{X} is conventionally bound to a command to insert @samp{X} in ! 14246: the buffer; @kbd{C-x m} is conventionally bound to a command to begin ! 14247: composing a mail message. @xref{Keys}. ! 14248: ! 14249: @item Completion ! 14250: Completion is what Emacs does when it automatically fills out an ! 14251: abbreviation for a name into the entire name. Completion is done for ! 14252: minibuffer (q.v.@:) arguments when the set of possible valid inputs ! 14253: is known; for example, on command names, buffer names, and ! 14254: file names. Completion occurs when @key{TAB}, @key{SPC} or @key{RET} ! 14255: is typed. @xref{Completion}.@refill ! 14256: ! 14257: @item Continuation Line ! 14258: When a line of text is longer than the width of the screen, it ! 14259: takes up more than one screen line when displayed. We say that the ! 14260: text line is continued, and all screen lines used for it after the ! 14261: first are called continuation lines. @xref{Basic,Continuation,Basic ! 14262: Editing}. ! 14263: ! 14264: @item Control-Character ! 14265: ASCII characters with octal codes 0 through 037, and also code 0177, ! 14266: do not have graphic images assigned to them. These are the control ! 14267: characters. Any control character can be typed by holding down the ! 14268: @key{CTRL} key and typing some other character; some have special keys ! 14269: on the keyboard. @key{RET}, @key{TAB}, @key{ESC}, @key{LFD} and ! 14270: @key{DEL} are all control characters. @xref{Characters}.@refill ! 14271: ! 14272: @item Copyleft ! 14273: A copyleft is a notice giving the public legal permission to redistribute ! 14274: a program or other work of art. Copylefts are used by leftists to enrich ! 14275: the public just as copyrights are used by rightists to gain power over ! 14276: the public. ! 14277: ! 14278: @item Current Buffer ! 14279: The current buffer in Emacs is the Emacs buffer on which most editing ! 14280: commands operate. You can select any Emacs buffer as the current one. ! 14281: @xref{Buffers}. ! 14282: ! 14283: @item Current Line ! 14284: The line point is on (@pxref{Point}). ! 14285: ! 14286: @item Current Paragraph ! 14287: The paragraph that point is in. If point is between paragraphs, the ! 14288: current paragraph is the one that follows point. @xref{Paragraphs}. ! 14289: ! 14290: @item Current Defun ! 14291: The defun (q.v.@:) that point is in. If point is between defuns, the ! 14292: current defun is the one that follows point. @xref{Defuns}. ! 14293: ! 14294: @item Cursor ! 14295: The cursor is the rectangle on the screen which indicates the position ! 14296: called point (q.v.@:) at which insertion and deletion takes place. ! 14297: The cursor is on or under the character that follows point. Often ! 14298: people speak of `the cursor' when, strictly speaking, they mean ! 14299: `point'. @xref{Basic,Cursor,Basic Editing}. ! 14300: ! 14301: @item Customization ! 14302: Customization is making minor changes in the way Emacs works. It is ! 14303: often done by setting variables (@pxref{Variables}) or by rebinding ! 14304: keys (@pxref{Keymaps}). ! 14305: ! 14306: @item Default Argument ! 14307: The default for an argument is the value that will be assumed if you ! 14308: do not specify one. When the minibuffer is used to read an argument, ! 14309: the default argument is used if you just type @key{RET}. ! 14310: @xref{Minibuffer}. ! 14311: ! 14312: @item Default Directory ! 14313: When you specify a file name that does not start with @samp{/} or @samp{~}, ! 14314: it is interpreted relative to the current buffer's default directory. ! 14315: @xref{Minibuffer File,Default Directory}. ! 14316: ! 14317: @item Defun ! 14318: A defun is a list at the top level of parenthesis or bracket structure ! 14319: in a program. It is so named because most such lists in Lisp programs ! 14320: are calls to the Lisp function @code{defun}. @xref{Defuns}. ! 14321: ! 14322: @item @key{DEL} ! 14323: @key{DEL} is a character that runs the command to delete one character of ! 14324: text. @xref{Basic,DEL,Basic Editing}. ! 14325: ! 14326: @item Deletion ! 14327: Deletion means erasing text without saving it. Emacs deletes text ! 14328: only when it is expected not to be worth saving (all whitespace, or ! 14329: only one character). The alternative is killing (q.v.@:). ! 14330: @xref{Killing,Deletion}. ! 14331: ! 14332: @item Deletion of Files ! 14333: Deleting a file means erasing it from the file system. ! 14334: @xref{Misc File Ops}. ! 14335: ! 14336: @item Deletion of Messages ! 14337: Deleting a message means flagging it to be eliminated from your mail ! 14338: file. This can be undone by undeletion until the mail file is expunged. ! 14339: @xref{Rmail Deletion}. ! 14340: ! 14341: @item Deletion of Windows ! 14342: Deleting a window means eliminating it from the screen. Other windows ! 14343: expand to use up the space. The deleted window can never come back, ! 14344: but no actual text is thereby lost. @xref{Windows}. ! 14345: ! 14346: @item Directory ! 14347: Files in the Unix file system are grouped into file directories. ! 14348: @xref{ListDir,,Directories}. ! 14349: ! 14350: @item Dired ! 14351: Dired is the Emacs facility that displays the contents of a file ! 14352: directory and allows you to ``edit the directory'', performing ! 14353: operations on the files in the directory. @xref{Dired}. ! 14354: ! 14355: @item Disabled Command ! 14356: A disabled command is one that you may not run without special ! 14357: confirmation. The usual reason for disabling a command is that it is ! 14358: confusing for beginning users. @xref{Disabling}. ! 14359: ! 14360: @item Dribble File ! 14361: A file into which Emacs writes all the characters that the user types ! 14362: on the keyboard. Dribble files are used to make a record for ! 14363: debugging Emacs bugs. Emacs does not make a dribble file unless you ! 14364: tell it to. @xref{Bugs}. ! 14365: ! 14366: @item Echo Area ! 14367: The echo area is the bottom line of the screen, used for echoing the ! 14368: arguments to commands, for asking questions, and printing brief ! 14369: messages (including error messages). @xref{Echo Area}. ! 14370: ! 14371: @item Echoing ! 14372: Echoing is acknowledging the receipt of commands by displaying them ! 14373: (in the echo area). Emacs never echoes single-character keys; longer ! 14374: keys echo only if you pause while typing them. ! 14375: ! 14376: @item Error ! 14377: An error occurs when an Emacs command cannot execute in the current ! 14378: circumstances. When an error occurs, execution of the command stops ! 14379: (unless the command has been programmed to do otherwise) and Emacs ! 14380: reports the error by printing an error message (q.v.). Type-ahead ! 14381: is discarded. Then Emacs is ready to read another editing command. ! 14382: ! 14383: @item Error Messages ! 14384: Error messages are single lines of output printed by Emacs when the ! 14385: user asks for something impossible to do (such as, killing text ! 14386: forward when point is at the end of the buffer). They appear in the ! 14387: echo area, accompanied by a beep. ! 14388: ! 14389: @item @key{ESC} ! 14390: @key{ESC} is a character, used to end incremental searches and as a ! 14391: prefix for typing Meta characters on keyboards lacking a @key{META} ! 14392: key. Unlike the @key{META} key (which, like the @key{SHIFT} key, is held ! 14393: down while another character is typed), the @key{ESC} key is pressed ! 14394: once and applies to the next character typed. ! 14395: ! 14396: @item Fill Prefix ! 14397: The fill prefix is a string that should be expected at the beginning ! 14398: of each line when filling is done. It is not regarded as part of the ! 14399: text to be filled. @xref{Filling}. ! 14400: ! 14401: @item Filling ! 14402: Filling text means moving text from line to line so that all the lines ! 14403: are approximately the same length. @xref{Filling}. ! 14404: ! 14405: @item Global ! 14406: Global means `independent of the current environment; in effect ! 14407: throughout Emacs'. It is the opposite of local (q.v.@:). Particular ! 14408: examples of the use of `global' appear below. ! 14409: ! 14410: @item Global Abbrev ! 14411: A global definition of an abbrev (q.v.@:) is effective in all major ! 14412: modes that do not have local (q.v.@:) definitions for the same abbrev. ! 14413: @xref{Abbrevs}. ! 14414: ! 14415: @item Global Keymap ! 14416: The global keymap (q.v.@:) contains key bindings that are in effect ! 14417: except when overridden by local key bindings in a major mode's local ! 14418: keymap (q.v.@:). @xref{Keymaps}. ! 14419: ! 14420: @item Global Substitution ! 14421: Global substitution means replacing each occurrence of one string by ! 14422: another string through a large amount of text. @xref{Replace}. ! 14423: ! 14424: @item Global Variable ! 14425: The global value of a variable (q.v.@:) takes effect in all buffers ! 14426: that do not have their own local (q.v.@:) values for the variable. ! 14427: @xref{Variables}. ! 14428: ! 14429: @item Graphic Character ! 14430: Graphic characters are those assigned pictorial images rather than ! 14431: just names. All the non-Meta (q.v.@:) characters except for the ! 14432: Control (q.v.@:) characters are graphic characters. These include ! 14433: letters, digits, punctuation, and spaces; they do not include ! 14434: @key{RET} or @key{ESC}. In Emacs, typing a graphic character inserts ! 14435: that character (in ordinary editing modes). @xref{Basic,,Basic Editing}. ! 14436: ! 14437: @item Grinding ! 14438: Grinding means adjusting the indentation in a program to fit the ! 14439: nesting structure. @xref{Indentation,Grinding}. ! 14440: ! 14441: @item Hardcopy ! 14442: Hardcopy means printed output. Emacs has commands for making printed ! 14443: listings of text in Emacs buffers. @xref{Hardcopy}. ! 14444: ! 14445: @item @key{HELP} ! 14446: You can type @key{HELP} at any time to ask what options you have, or ! 14447: to ask what any command does. @key{HELP} is really @kbd{Control-h}. ! 14448: @xref{Help}. ! 14449: ! 14450: @item Inbox ! 14451: An inbox is a file in which mail is delivered by the operating system. ! 14452: Rmail transfers mail from inboxes to mail files (q.v.) in which the ! 14453: mail is then stored permanently or until explicitly deleted. ! 14454: @xref{Rmail Inbox}. ! 14455: ! 14456: @item Indentation ! 14457: Indentation means blank space at the beginning of a line. Most ! 14458: programming languages have conventions for using indentation to ! 14459: illuminate the structure of the program, and Emacs has special ! 14460: features to help you set up the correct indentation. ! 14461: @xref{Indentation}. ! 14462: ! 14463: @item Insertion ! 14464: Insertion means copying text into the buffer, either from the keyboard ! 14465: or from some other place in Emacs. ! 14466: ! 14467: @item Justification ! 14468: Justification means adding extra spaces to lines of text to make them ! 14469: come exactly to a specified width. @xref{Filling,Justification}. ! 14470: ! 14471: @item Keyboard Macros ! 14472: Keyboard macros are a way of defining new Emacs commands from ! 14473: sequences of existing ones, with no need to write a Lisp program. ! 14474: @xref{Keyboard Macros}. ! 14475: ! 14476: @item Key ! 14477: A key is a sequence of characters that, when input to Emacs, specify ! 14478: or begin to specify a single action for Emacs to perform. That is, ! 14479: the sequence is not more than a single unit. If the key is enough to ! 14480: specify one action, it is a complete key (q.v.); if it is less than ! 14481: enough, it is a prefix key (q.v.). @xref{Keys}. ! 14482: ! 14483: @item Keymap ! 14484: The keymap is the data structure that records the bindings (q.v.@:) of ! 14485: keys to the commands that they run. For example, the keymap binds the ! 14486: character @kbd{C-n} to the command function @code{next-line}. ! 14487: @xref{Keymaps}. ! 14488: ! 14489: @item Kill Ring ! 14490: The kill ring is where all text you have killed recently is saved. ! 14491: You can reinsert any of the killed text still in the ring; this is ! 14492: called yanking (q.v.@:). @xref{Yanking}. ! 14493: ! 14494: @item Killing ! 14495: Killing means erasing text and saving it on the kill ring so it can be ! 14496: yanked (q.v.@:) later. Some other systems call this ``cutting''. ! 14497: Most Emacs commands to erase text do killing, as opposed to deletion ! 14498: (q.v.@:). @xref{Killing}. ! 14499: ! 14500: @item Killing Jobs ! 14501: Killing a job (such as, an invocation of Emacs) means making it cease ! 14502: to exist. Any data within it, if not saved in a file, is lost. ! 14503: @xref{Exiting}. ! 14504: ! 14505: @item List ! 14506: A list is, approximately, a text string beginning with an open ! 14507: parenthesis and ending with the matching close parenthesis. In C mode ! 14508: and other non-Lisp modes, groupings surrounded by other kinds of matched ! 14509: delimiters appropriate to the language, such as braces, are also ! 14510: considered lists. Emacs has special commands for many operations on ! 14511: lists. @xref{Lists}. ! 14512: ! 14513: @item Local ! 14514: Local means `in effect only in a particular context'; the relevant ! 14515: kind of context is a particular function execution, a particular ! 14516: buffer, or a particular major mode. It is the opposite of `global' ! 14517: (q.v.@:). Specific uses of `local' in Emacs terminology appear below. ! 14518: ! 14519: @item Local Abbrev ! 14520: A local abbrev definition is effective only if a particular major mode ! 14521: is selected. In that major mode, it overrides any global definition ! 14522: for the same abbrev. @xref{Abbrevs}. ! 14523: ! 14524: @item Local Keymap ! 14525: A local keymap is used in a particular major mode; the key bindings ! 14526: (q.v.@:) in the current local keymap override global bindings of the ! 14527: same keys. @xref{Keymaps}. ! 14528: ! 14529: @item Local Variable ! 14530: A local value of a variable (q.v.@:) applies to only one buffer. ! 14531: @xref{Locals}. ! 14532: ! 14533: @item M- ! 14534: @kbd{M-} in the name of a character is an abbreviation for @key{META}, ! 14535: one of the modifier keys that can accompany any character. ! 14536: @xref{Characters}. ! 14537: ! 14538: @item M-C- ! 14539: @samp{M-C-} in the name of a character is an abbreviation for ! 14540: Control-Meta; it means the same thing as @samp{C-M-}. If your ! 14541: terminal lacks a real @key{META} key, you type a Control-Meta character by ! 14542: typing @key{ESC} and then typing the corresponding Control character. ! 14543: @xref{Characters,C-M-}. ! 14544: ! 14545: @item M-x ! 14546: @kbd{M-x} is the key which is used to call an Emacs command by name. ! 14547: This is how commands that are not bound to keys are called. ! 14548: @xref{M-x}. ! 14549: ! 14550: @item Mail ! 14551: Mail means messages sent from one user to another through the computer ! 14552: system, to be read at the recipient's convenience. Emacs has commands for ! 14553: composing and sending mail, and for reading and editing the mail you have ! 14554: received. @xref{Sending Mail}. @xref{Rmail}, for how to read mail. ! 14555: ! 14556: @item Mail File ! 14557: A mail file is a file which is edited using Rmail and in which Rmail ! 14558: stores mail. @xref{Rmail}. ! 14559: ! 14560: @item Major Mode ! 14561: The major modes are a mutually exclusive set of options each of which ! 14562: configures Emacs for editing a certain sort of text. Ideally, each ! 14563: programming language has its own major mode. @xref{Major Modes}. ! 14564: ! 14565: @item Mark ! 14566: The mark points to a position in the text. It specifies one end of ! 14567: the region (q.v.@:), point being the other end. Many commands operate ! 14568: on all the text from point to the mark. @xref{Mark}. ! 14569: ! 14570: @item Mark Ring ! 14571: The mark ring is used to hold several recent previous locations of the ! 14572: mark, just in case you want to move back to them. @xref{Mark Ring}. ! 14573: ! 14574: @item Message ! 14575: See `mail'. ! 14576: ! 14577: @item Meta ! 14578: Meta is the name of a modifier bit which a command character may have. ! 14579: It is present in a character if the character is typed with the ! 14580: @key{META} key held down. Such characters are given names that start ! 14581: with @kbd{Meta-}. For example, @kbd{Meta-<} is typed by holding down ! 14582: @key{META} and at the same time typing @kbd{<} (which itself is done, ! 14583: on most terminals, by holding down @key{SHIFT} and typing @kbd{,}). ! 14584: @xref{Characters,Meta}. ! 14585: ! 14586: @item Meta Character ! 14587: A Meta character is one whose character code includes the Meta bit. ! 14588: ! 14589: @item Minibuffer ! 14590: The minibuffer is the window that appears when necessary inside the ! 14591: echo area (q.v.@:), used for reading arguments to commands. ! 14592: @xref{Minibuffer}. ! 14593: ! 14594: @item Minor Mode ! 14595: A minor mode is an optional feature of Emacs which can be switched on ! 14596: or off independently of all other features. Each minor mode has a ! 14597: command to turn it on or off. @xref{Minor Modes}. ! 14598: ! 14599: @item Mode Line ! 14600: The mode line is the line at the bottom of each text window (q.v.@:), ! 14601: which gives status information on the buffer displayed in that window. ! 14602: @xref{Mode Line}. ! 14603: ! 14604: @item Modified Buffer ! 14605: A buffer (q.v.@:) is modified if its text has been changed since the ! 14606: last time the buffer was saved (or since when it was created, if it ! 14607: has never been saved). @xref{Saving}. ! 14608: ! 14609: @item Moving Text ! 14610: Moving text means erasing it from one place and inserting it in ! 14611: another. This is done by killing (q.v.@:) and then yanking (q.v.@:). ! 14612: @xref{Killing}. ! 14613: ! 14614: @item Named Mark ! 14615: A named mark is a register (q.v.@:) in its role of recording a ! 14616: location in text so that you can move point to that location. ! 14617: @xref{Registers}. ! 14618: ! 14619: @item Narrowing ! 14620: Narrowing means creating a restriction (q.v.@:) that limits editing in ! 14621: the current buffer to only a part of the text in the buffer. Text ! 14622: outside that part is inaccessible to the user until the boundaries are ! 14623: widened again, but it is still there, and saving the file saves it ! 14624: all. @xref{Narrowing}. ! 14625: ! 14626: @item Newline ! 14627: @key{LFD} characters in the buffer terminate lines of text and are ! 14628: called newlines. @xref{Characters,Newline}. ! 14629: ! 14630: @item Numeric Argument ! 14631: A numeric argument is a number, specified before a command, to change ! 14632: the effect of the command. Often the numeric argument serves as a ! 14633: repeat count. @xref{Arguments}. ! 14634: ! 14635: @item Option ! 14636: An option is a variable (q.v.@:) that exists so that you can customize ! 14637: Emacs by giving it a new value. @xref{Variables}. ! 14638: ! 14639: @item Overwrite Mode ! 14640: Overwrite mode is a minor mode. When it is enabled, ordinary text ! 14641: characters replace the existing text after point rather than pushing ! 14642: it to the right. @xref{Minor Modes}. ! 14643: ! 14644: @item Page ! 14645: A page is a unit of text, delimited by formfeed characters (ASCII ! 14646: Control-L, code 014) coming at the beginning of a line. Some Emacs ! 14647: commands are provided for moving over and operating on pages. ! 14648: @xref{Pages}. ! 14649: ! 14650: @item Paragraphs ! 14651: Paragraphs are the medium-size unit of English text. There are ! 14652: special Emacs commands for moving over and operating on paragraphs. ! 14653: @xref{Paragraphs}. ! 14654: ! 14655: @item Parsing ! 14656: We say that Emacs parses words or expressions in the text being ! 14657: edited. Really, all it knows how to do is find the other end of a ! 14658: word or expression. @xref{Syntax}. ! 14659: ! 14660: @item Point ! 14661: Point is the place in the buffer at which insertion and deletion ! 14662: occur. Point is considered to be between two characters, not at one ! 14663: character. The terminal's cursor (q.v.@:) indicates the location of ! 14664: point. @xref{Basic,Point}. ! 14665: ! 14666: @item Prefix Key ! 14667: A prefix key is a key (q.v.@:) whose sole function is to introduce a ! 14668: set of multi-character keys. @kbd{Control-x} is an example of prefix ! 14669: key; thus, any two-character sequence starting with @kbd{C-x} is also ! 14670: a legitimate key. @xref{Keys}. ! 14671: ! 14672: @item Primary Mail File ! 14673: Your primary mail file is the file named @samp{RMAIL} in your home ! 14674: directory, where all mail that you receive is stored by Rmail unless you ! 14675: make arrangements to do otherwise. @xref{Rmail}. ! 14676: ! 14677: @item Prompt ! 14678: A prompt is text printed to ask the user for input. Printing a prompt ! 14679: is called prompting. Emacs prompts always appear in the echo area ! 14680: (q.v.@:). One kind of prompting happens when the minibuffer is used ! 14681: to read an argument (@pxref{Minibuffer}); the echoing which happens ! 14682: when you pause in the middle of typing a multicharacter key is also a ! 14683: kind of prompting (@pxref{Echo Area}). ! 14684: ! 14685: @item Quitting ! 14686: Quitting means cancelling a partially typed command or a running ! 14687: command, using @kbd{C-g}. @xref{Quitting}. ! 14688: ! 14689: @item Quoting ! 14690: Quoting means depriving a character of its usual special significance. ! 14691: In Emacs this is usually done with @kbd{Control-q}. What constitutes special ! 14692: significance depends on the context and on convention. For example, ! 14693: an ``ordinary'' character as an Emacs command inserts itself; so in ! 14694: this context, a special character is any character that does not ! 14695: normally insert itself (such as @key{DEL}, for example), and quoting ! 14696: it makes it insert itself as if it were not special. Not all contexts ! 14697: allow quoting. @xref{Basic,Quoting,Basic Editing}. ! 14698: ! 14699: @item Read-only Buffer ! 14700: A read-only buffer is one whose text you are not allowed to change. ! 14701: Normally Emacs makes buffers read-only when they contain text which ! 14702: has a special significance to Emacs; for example, Dired buffers. ! 14703: Visiting a file that is write protected also makes a read-only buffer. ! 14704: @xref{Buffers}. ! 14705: ! 14706: @item Recursive Editing Level ! 14707: A recursive editing level is a state in which part of the execution of ! 14708: a command involves asking the user to edit some text. This text may ! 14709: or may not be the same as the text to which the command was applied. ! 14710: The mode line indicates recursive editing levels with square brackets ! 14711: (@samp{[} and @samp{]}). @xref{Recursive Edit}. ! 14712: ! 14713: @item Redisplay ! 14714: Redisplay is the process of correcting the image on the screen to ! 14715: correspond to changes that have been made in the text being edited. ! 14716: @xref{Screen,Redisplay}. ! 14717: ! 14718: @item Regexp ! 14719: See `regular expression'. ! 14720: ! 14721: @item Region ! 14722: The region is the text between point (q.v.@:) and the mark (q.v.@:). ! 14723: Many commands operate on the text of the region. @xref{Mark,Region}. ! 14724: ! 14725: @item Registers ! 14726: Registers are named slots in which text or buffer positions or ! 14727: rectangles can be saved for later use. @xref{Registers}. ! 14728: ! 14729: @item Regular Expression ! 14730: A regular expression is a pattern that can match various text strings; ! 14731: for example, @samp{l[0-9]+} matches @samp{l} followed by one or more ! 14732: digits. @xref{Regexps}. ! 14733: ! 14734: @item Replacement ! 14735: See `global substitution'. ! 14736: ! 14737: @item Restriction ! 14738: A buffer's restriction is the amount of text, at the beginning or the ! 14739: end of the buffer, that is temporarily invisible and inaccessible. ! 14740: Giving a buffer a nonzero amount of restriction is called narrowing ! 14741: (q.v.). @xref{Narrowing}. ! 14742: ! 14743: @item @key{RET} ! 14744: @key{RET} is a character than in Emacs runs the command to insert a ! 14745: newline into the text. It is also used to terminate most arguments ! 14746: read in the minibuffer (q.v.@:). @xref{Characters,Return}. ! 14747: ! 14748: @item Saving ! 14749: Saving a buffer means copying its text into the file that was visited ! 14750: (q.v.@:) in that buffer. This is the way text in files actually gets ! 14751: changed by your Emacs editing. @xref{Saving}. ! 14752: ! 14753: @item Scrolling ! 14754: Scrolling means shifting the text in the Emacs window so as to see a ! 14755: different part of the buffer. @xref{Display,Scrolling}. ! 14756: ! 14757: @item Searching ! 14758: Searching means moving point to the next occurrence of a specified ! 14759: string. @xref{Search}. ! 14760: ! 14761: @item Selecting ! 14762: Selecting a buffer means making it the current (q.v.@:) buffer. ! 14763: @xref{Buffers,Selecting}. ! 14764: ! 14765: @item Self-documentation ! 14766: Self-documentation is the feature of Emacs which can tell you what any ! 14767: command does, or give you a list of all commands related to a topic ! 14768: you specify. You ask for self-documentation with the help character, ! 14769: @kbd{C-h}. @xref{Help}. ! 14770: ! 14771: @item Sentences ! 14772: Emacs has commands for moving by or killing by sentences. ! 14773: @xref{Sentences}. ! 14774: ! 14775: @item Sexp ! 14776: A sexp (short for `s-expression') is the basic syntactic unit of Lisp ! 14777: in its textual form: either a list, or Lisp atom. Many Emacs commands ! 14778: operate on sexps. The term `sexp' is generalized to languages other ! 14779: than Lisp, to mean a syntactically recognizable expression. ! 14780: @xref{Lists,Sexps}. ! 14781: ! 14782: @item Simultaneous Editing ! 14783: Simultaneous editing means two users modifying the same file at once. ! 14784: Simultaneous editing if not detected can cause one user to lose his ! 14785: work. Emacs detects all cases of simultaneous editing and warns the ! 14786: user to investigate them. @xref{Interlocking,,Simultaneous Editing}. ! 14787: ! 14788: @item String ! 14789: A string is a kind of Lisp data object which contains a sequence of ! 14790: characters. Many Emacs variables are intended to have strings as ! 14791: values. The Lisp syntax for a string consists of the characters in ! 14792: the string with a @samp{"} before and another @samp{"} after. A ! 14793: @samp{"} that is part of the string must be written as @samp{\"} and a ! 14794: @samp{\} that is part of the string must be written as @samp{\\}. All ! 14795: other characters, including newline, can be included just by writing ! 14796: them inside the string; however, escape sequences as in C, such as ! 14797: @samp{\n} for newline or @samp{\241} using an octal character code, ! 14798: are allowed as well. ! 14799: ! 14800: @item String Substitution ! 14801: See `global substitution'. ! 14802: ! 14803: @item Syntax Table ! 14804: The syntax table tells Emacs which characters are part of a word, ! 14805: which characters balance each other like parentheses, etc. ! 14806: @xref{Syntax}. ! 14807: ! 14808: @item Tag Table ! 14809: A tag table is a file that serves as an index to the function ! 14810: definitions in one or more other files. @xref{Tags}. ! 14811: ! 14812: @item Termscript File ! 14813: A termscript file contains a record of all characters sent by Emacs to ! 14814: the terminal. It is used for tracking down bugs in Emacs redisplay. ! 14815: Emacs does not make a termscript file unless you tell it to. ! 14816: @xref{Bugs}. ! 14817: ! 14818: @item Text ! 14819: Two meanings (@pxref{Text}): ! 14820: ! 14821: @itemize @bullet ! 14822: @item ! 14823: Data consisting of a sequence of characters, as opposed to binary ! 14824: numbers, images, graphics commands, executable programs, and the like. ! 14825: The contents of an Emacs buffer are always text in this sense. ! 14826: @item ! 14827: Data consisting of written human language, as opposed to programs, ! 14828: or following the stylistic conventions of human language. ! 14829: @end itemize ! 14830: ! 14831: @item Top Level ! 14832: Top level is the normal state of Emacs, in which you are editing the ! 14833: text of the file you have visited. You are at top level whenever you ! 14834: are not in a recursive editing level (q.v.@:) or the minibuffer ! 14835: (q.v.@:), and not in the middle of a command. You can get back to top ! 14836: level by aborting (q.v.@:) and quitting (q.v.@:). @xref{Quitting}. ! 14837: ! 14838: @item Transposition ! 14839: Transposing two units of text means putting each one into the place ! 14840: formerly occupied by the other. There are Emacs commands to transpose ! 14841: two adjacent characters, words, sexps (q.v.@:) or lines ! 14842: (@pxref{Transpose}). ! 14843: ! 14844: @item Truncation ! 14845: Truncating text lines in the display means leaving out any text on a ! 14846: line that does not fit within the right margin of the window ! 14847: displaying it. See also `continuation line'. ! 14848: @xref{Basic,Truncation,Basic Editing}. ! 14849: ! 14850: @item Undoing ! 14851: Undoing means making your previous editing go in reverse, bringing ! 14852: back the text that existed earlier in the editing session. ! 14853: @xref{Undo}. ! 14854: ! 14855: @item Variable ! 14856: A variable is an object in Lisp that can store an arbitrary value. ! 14857: Emacs uses some variables for internal purposes, and has others (known ! 14858: as `options' (q.v.@:)) just so that you can set their values to ! 14859: control the behavior of Emacs. The variables used in Emacs that you ! 14860: are likely to be interested in are listed in the Variables Index in ! 14861: this manual. @xref{Variables}, for information on variables. ! 14862: ! 14863: @item Visiting ! 14864: Visiting a file means loading its contents into a buffer (q.v.@:) ! 14865: where they can be edited. @xref{Visiting}. ! 14866: ! 14867: @item Whitespace ! 14868: Whitespace is any run of consecutive formatting characters (space, ! 14869: tab, newline, and backspace). ! 14870: ! 14871: @item Widening ! 14872: Widening is removing any restriction (q.v.@:) on the current buffer; ! 14873: it is the opposite of narrowing (q.v.@:). @xref{Narrowing}. ! 14874: ! 14875: @item Window ! 14876: Emacs divides the screen into one or more windows, each of which can ! 14877: display the contents of one buffer (q.v.@:) at any time. ! 14878: @xref{Screen}, for basic information on how Emacs uses the screen. ! 14879: @xref{Windows}, for commands to control the use of windows. ! 14880: ! 14881: @item Word Abbrev ! 14882: Synonymous with `abbrev'. ! 14883: ! 14884: @item Word Search ! 14885: Word search is searching for a sequence of words, considering the ! 14886: punctuation between them as insignificant. @xref{Word Search}. ! 14887: ! 14888: @item Yanking ! 14889: Yanking means reinserting text previously killed. It can be used to ! 14890: undo a mistaken kill, or for copying or moving text. Some other ! 14891: systems call this ``pasting''. @xref{Yanking}. ! 14892: @end table ! 14893: ! 14894: @node Key Index, Command Index, Glossary, Top ! 14895: @unnumbered Key (Character) Index ! 14896: @printindex ky ! 14897: ! 14898: @node Command Index, Variable Index, Key Index, Top ! 14899: @unnumbered Command and Function Index ! 14900: @printindex fn ! 14901: ! 14902: @node Variable Index, Concept Index, Command Index, Top ! 14903: @unnumbered Variable Index ! 14904: @printindex vr ! 14905: ! 14906: @node Concept Index, Screen, Variable Index, Top ! 14907: @unnumbered Concept Index ! 14908: @printindex cp ! 14909: ! 14910: @summarycontents ! 14911: @contents ! 14912: @bye
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.