GNU Emacs Manual
GNU Emacs Manual
Seventeenth Edition, Updated for Emacs Version 24.5.
Richard Stallman et al.
This is the Seventeenth edition of the GNU Emacs Manual, updated for Emacs version 24.5.
Copyright © 1985-1987, 1993-2015 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with the Invariant Sections being "The GNU Manifesto," "Distribution" and "GNU GENERAL PUBLIC LICENSE," with the Front-Cover Texts being "A GNU Manual," and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled "GNU Free Documentation License."
(a) The FSF's Back-Cover Text is: "You have the freedom to copy and modify this GNU manual. Buying copies from the FSF supports it in developing GNU and promoting software freedom."
Published by the Free Software Foundation 51 Franklin Street, Fifth Floor Boston, MA 02110-1301 USA ISBN 978-0-9831592-5-4
Cover art by Etienne Suvasa; cover design by Matt Lee.
Short Contents
Preface 1
Distribution 2
Introduction 5
1 The Organization of the Screen 6
2 Characters, Keys and Commands 11
3 Entering and Exiting Emacs 14
4 Basic Editing Commands 16
5 The Minibuffer 26
6 Running Commands by Name 36
7 Help 37
8 The Mark and the Region 45
9 Killing and Moving Text 52
10 Registers 64
11 Controlling the Display 69
12 Searching and Replacement 90
13 Commands for Fixing Typos 109
14 Keyboard Macros 114
15 File Handling 122
16 Using Multiple Buffers 147
17 Multiple Windows 156
18 Frames and Graphical Displays 162
19 International Character Set Support 177
20 Major and Minor Modes 199
21 Indentation 205
22 Commands for Human Languages 208
23 Editing Programs 240
24 Compiling and Testing Programs 261
25 Maintaining Large Programs 281
26 Abbrevs 309
27 Dired, the Directory Editor 315
28 The Calendar and the Diary 331
29 Sending Mail 350
30 Reading Mail with Rmail 359
31 Miscellaneous Commands 379
32 Emacs Lisp Packages 408
ii
33 Customization 412
34 Dealing with Common Problems 443
A GNU GENERAL PUBLIC LICENSE 459
B GNU Free Documentation License 470
C Command Line Arguments for Emacs Invocation 478
D X Options and Resources 493
E Emacs 23 Antinews 500
F Emacs and Mac OS / GNUstep 502
G Emacs and Microsoft Windows/MS-DOS 505
The GNU Manifesto 515
Glossary 523
Key (Character) Index 546
Command and Function Index 555
Variable Index 568
Concept Index 575
iii
Table of Contents
Preface 1
Distribution 2
Acknowledgments 2
Introduction 5
1 The Organization of the Screen 6
1.1 Point 6
1.2 The Echo Area 7
1.3 The Mode Line 8
1.4 The Menu Bar 9
2 Characters, Keys and Commands 11
2.1 Kinds of User Input 11
2.2 Keys 11
2.3 Keys and Commands 12
3 Entering and Exiting Emacs 14
3.1 Entering Emacs 14
3.2 Exiting Emacs 15
4 Basic Editing Commands 16
4.1 Inserting Text 16
4.2 Changing the Location of Point 17
4.3 Erasing Text 19
4.4 Undoing Changes 20
4.5 Files 20
4.6 Help 21
4.7 Blank Lines 21
4.8 Continuation Lines 22
4.9 Cursor Position Information 22
4.10 Numeric Arguments 23
4.11 Repeating a Command 25
iv
5 The Minibuffer 26
5.1 Using the Minibuffer 26
5.2 Minibuffers for File Names 26
5.3 Editing in the Minibuffer 27
5.4 Completion 28
5.4.1 Completion Example 28
5.4.2 Completion Commands 29
5.4.3 Completion Exit 30
5.4.4 How Completion Alternatives Are Chosen 31
5.4.5 Completion Options 32
5.5 Minibuffer History 32
5.6 Repeating Minibuffer Commands 34
5.7 Entering passwords 34
5.8 Yes or No Prompts 35
6 Running Commands by Name 36
7 Help 37
7.1 Documentation for a Key 39
7.2 Help by Command or Variable Name 39
7.3 Apropos 40
7.4 Help Mode Commands 41
7.5 Keyword Search for Packages 42
7.6 Help for International Language Support 42
7.7 Other Help Commands 43
7.8 Help Files 43
7.9 Help on Active Text and Tooltips 44
8 The Mark and the Region 45
8.1 Setting the Mark 45
8.2 Commands to Mark Textual Objects 47
8.3 Operating on the Region 47
8.4 The Mark Ring 48
8.5 The Global Mark Ring 49
8.6 Shift Selection 49
8.7 Disabling Transient Mark Mode 50
9 Killing and Moving Text 52
9.1 Deletion and Killing 52
9.1.1 Deletion 52
9.1.2 Killing by Lines 53
9.1.3 Other Kill Commands 54
9.1.4 Options for Killing 54
9.2 Yanking 55
9.2.1 The Kill Ring 55
9.2.2 Yanking Earlier Kills 55
9.2.3 Appending Kills 56
9.3 "Cut and Paste" Operations on Graphical Displays 57
9.3.1 Using the Clipboard 57
9.3.2 Cut and Paste with Other Window Applications 58
9.3.3 Secondary Selection 58
9.4 Accumulating Text 59
9.5 Rectangles 60
9.6 CUA Bindings 62
10 Registers 64
10.1 Saving Positions in Registers 64
10.2 Saving Text in Registers 64
10.3 Saving Rectangles in Registers 65
10.4 Saving Window Configurations in Registers 66
10.5 Keeping Numbers in Registers 66
10.6 Keeping File Names in Registers 66
10.7 Keyboard Macro Registers 67
10.8 Bookmarks 67
11 Controlling the Display 69
11.1 Scrolling 69
11.2 Recentering 70
11.3 Automatic Scrolling 71
11.4 Horizontal Scrolling 72
11.5 Narrowing 73
11.6 View Mode 73
11.7 Follow Mode 74
11.8 Text Faces 74
11.9 Colors for Faces 75
11.10 Standard Faces 75
11.11 Text Scale 78
11.12 Font Lock mode 78
11.13 Interactive Highlighting 80
11.14 Window Fringes 81
11.15 Displaying Boundaries 82
11.16 Useless Whitespace 82
11.17 Selective Display 83
11.18 Optional Mode Line Features 84
vi
11.19 How Text Is Displayed 85
11.20 Displaying the Cursor 86
11.21 Line Truncation 87
11.22 Visual Line Mode 87
11.23 Customization of Display 88
12 Searching and Replacement 90
12.1 Incremental Search 90
12.1.1 Basics of Incremental Search 90
12.1.2 Repeating Incremental Search 91
12.1.3 Errors in Incremental Search 91
12.1.4 Special Input for Incremental Search 92
12.1.5 Isearch Yanking 93
12.1.6 Not Exiting Incremental Search 93
12.1.7 Searching the Minibuffer 94
12.2 Nonincremental Search 95
12.3 Word Search 95
12.4 Symbol Search 96
12.5 Regular Expression Search 96
12.6 Syntax of Regular Expressions 97
12.7 Backslash in Regular Expressions 100
12.8 Regular Expression Example 102
12.9 Searching and Case 102
12.10 Replacement Commands 103
12.10.1 Unconditional Replacement 103
12.10.2 Regexp Replacement 103
12.10.3 Replace Commands and Case 104
12.10.4 Query Replace 105
12.11 Other Search-and-Loop Commands 107
13 Commands for Fixing Typos 109
13.1 Undo 109
13.2 Transposing Text 110
13.3 Case Conversion Ill
13.4 Checking and Correcting Spelling Ill
14 Keyboard Macros 114
14.1 Basic Use 114
14.2 The Keyboard Macro Ring 115
14.3 The Keyboard Macro Counter 116
14.4 Executing Macros with Variations 118
14.5 Naming and Saving Keyboard Macros 118
14.6 Editing a Keyboard Macro 119
14.7 Stepwise Editing a Keyboard Macro 120
vii
15 File Handling 122
15.1 File Names 122
15.2 Visiting Files 123
15.3 Saving Files 126
15.3.1 Commands for Saving Files 126
15.3.2 Backup Files 127
15.3.2.1 Single or Numbered Backups 128
15.3.2.2 Automatic Deletion of Backups 129
15.3.2.3 Copying vs. Renaming 129
15.3.3 Customizing Saving of Files 130
15.3.4 Protection against Simultaneous Editing 130
15.3.5 Shadowing Files 131
15.3.6 Updating Time Stamps Automatically 132
15.4 Reverting a Buffer 132
15.5 Auto-Saving: Protection Against Disasters 133
15.5.1 Auto- Save Files 133
15.5.2 Controlling Auto-Saving 134
15.5.3 Recovering Data from Auto-Saves 135
15.6 File Name Aliases 135
15.7 File Directories 136
15.8 Comparing Files 137
15.9 Diff Mode 138
15.10 Miscellaneous File Operations 140
15.11 Accessing Compressed Files 141
15.12 File Archives 141
15.13 Remote Files 142
15.14 Quoted File Names 143
15.15 File Name Cache 144
15.16 Convenience Features for Finding Files 144
15.17 Filesets 145
16 Using Multiple Buffers 147
16.1 Creating and Selecting Buffers 147
16.2 Listing Existing Buffers 149
16.3 Miscellaneous Buffer Operations 149
16.4 Killing Buffers 150
16.5 Operating on Several Buffers 151
16.6 Indirect Buffers 153
16.7 Convenience Features and Customization of Buffer Handling 153
16.7.1 Making Buffer Names Unique 154
16.7.2 Fast minibuffer selection 154
16.7.3 Customizing Buffer Menus 155
viii
17 Multiple Windows 156
17.1 Concepts of Emacs Windows 156
17.2 Splitting Windows 156
17.3 Using Other Windows 157
17.4 Displaying in Another Window 158
17.5 Deleting and Rearranging Windows 159
17.6 Displaying a Buffer in a Window 160
17.6.1 How display-buffer works 160
17.7 Convenience Features for Window Handling 161
18 Frames and Graphical Displays 162
18.1 Mouse Commands for Editing 162
18.2 Mouse Commands for Words and Lines 164
18.3 Following References with the Mouse 164
18.4 Mouse Clicks for Menus 165
18.5 Mode Line Mouse Commands 165
18.6 Creating Frames 166
18.7 Frame Commands 167
18.8 Fonts 168
18.9 Speedbar Frames 171
18.10 Multiple Displays 171
18.11 Frame Parameters 172
18.12 Scroll Bars 172
18.13 Drag and Drop 173
18.14 Menu Bars 173
18.15 Tool Bars 173
18.16 Using Dialog Boxes 174
18.17 Tooltips 174
18.18 Mouse Avoidance 175
18.19 Non- Window Terminals 175
18.20 Using a Mouse in Text Terminals 176
19 International Character Set Support 177
19.1 Introduction to International Character Sets 177
19.2 Language Environments 179
19.3 Input Methods 181
19.4 Selecting an Input Method 182
19.5 Coding Systems 183
19.6 Recognizing Coding Systems 185
19.7 Specifying a File's Coding System 187
19.8 Choosing Coding Systems for Output 187
19.9 Specifying a Coding System for File Text 188
19.10 Coding Systems for Interprocess Communication 189
19.11 Coding Systems for File Names 190
19.12 Coding Systems for Terminal I/O 191
19.13 Fontsets 192
19.14 Defining fontsets 192
ix
19.15 Modifying Fontsets 194
19.16 Undisplayable Characters 195
19.17 Unibyte Editing Mode 195
19.18 Charsets 196
19.19 Bidirectional Editing 197
20 Major and Minor Modes 199
20.1 Major Modes 199
20.2 Minor Modes 200
20.3 Choosing File Modes 202
21 Indentation 205
21.1 Indentation Commands 205
21.2 Tab Stops 206
21.3 Tabs vs. Spaces 207
21.4 Convenience Features for Indentation 207
22 Commands for Human Languages 208
22.1 Words 208
22.2 Sentences 209
22.3 Paragraphs 210
22.4 Pages 211
22.5 Filling Text 212
22.5.1 Auto Fill Mode 212
22.5.2 Explicit Fill Commands 213
22.5.3 The Fill Prefix 214
22.5.4 Adaptive Filling 215
22.6 Case Conversion Commands 216
22.7 Text Mode 217
22.8 Outline Mode 217
22.8.1 Format of Outlines 218
22.8.2 Outline Motion Commands 219
22.8.3 Outline Visibility Commands 219
22.8.4 Viewing One Outline in Multiple Views 221
22.8.5 Folding Editing 221
22.9 Org Mode 222
22.9.1 Org as an organizer 223
22.9.2 Org as an authoring system 223
22.10 TEXMode 224
22.10.1 TgX Editing Commands 224
22.10.2 MgX Editing Commands 225
22.10.3 TeX Printing Commands 226
22.10.4 TgX Mode Miscellany 228
22.11 SGML and HTML Modes 228
22.12 NroffMode 229
22.13 Enriched Text 230
22.13.1 Enriched Mode 230
22.13.2 Hard and Soft Newlines 230
22.13.3 Editing Format Information 231
22.13.4 Faces in Enriched Text 231
22.13.5 Indentation in Enriched Text 232
22.13.6 Justification in Enriched Text 233
22.13.7 Setting Other Text Properties 233
22.14 Editing Text-based Tables 233
22.14.1 What is a Text-based Table? 234
22.14.2 Creating a Table 234
22.14.3 Table Recognition 234
22.14.4 Commands for Table Cells 235
22.14.5 Cell Justification 236
22.14.6 Table Rows and Columns 236
22.14.7 Converting Between Plain Text and Tables 236
22.14.8 Table Miscellany 237
22.15 Two-Column Editing 238
23 Editing Programs 240
23.1 Major Modes for Programming Languages 240
23.2 Top-Level Definitions, or Defuns 241
23.2.1 Left Margin Convention 241
23.2.2 Moving by Defuns 241
23.2.3 Imenu 242
23.2.4 Which Function Mode 243
23.3 Indentation for Programs 243
23.3.1 Basic Program Indentation Commands 243
23.3.2 Indenting Several Lines 244
23.3.3 Customizing Lisp Indentation 244
23.3.4 Commands for C Indentation 245
23.3.5 Customizing C Indentation 245
23.4 Commands for Editing with Parentheses 246
23.4.1 Expressions with Balanced Parentheses 246
23.4.2 Moving in the Parenthesis Structure 248
23.4.3 Matching Parentheses 248
23.5 Manipulating Comments 249
23.5.1 Comment Commands 249
23.5.2 Multiple Lines of Comments 251
23.5.3 Options Controlling Comments 251
23.6 Documentation Lookup 252
23.6.1 Info Documentation Lookup 252
23.6.2 Man Page Lookup 252
23.6.3 Emacs Lisp Documentation Lookup 253
23.7 Hideshow minor mode 253
23.8 Completion for Symbol Names 254
23.9 MixedCase Words 255
23.10 Semantic 255
23.11 Other Features Useful for Editing Programs 256
23.12 C and Related Modes 256
xi
23.12.1 C Mode Motion Commands 256
23.12.2 Electric C Characters 257
23.12.3 Hungry Delete Feature in C 258
23.12.4 Other Commands for C Mode 258
23.13 Asm Mode 260
24 Compiling and Testing Programs 261
24.1 Running Compilations under Emacs 261
24.2 Compilation Mode 262
24.3 Subshells for Compilation 264
24.4 Searching with Grep under Emacs 264
24.5 Finding Syntax Errors On The Fly 266
24.6 Running Debuggers Under Emacs 266
24.6.1 Starting GUD 266
24.6.2 Debugger Operation 267
24.6.3 Commands of GUD 268
24.6.4 GUD Customization 270
24.6.5 GDB Graphical Interface 270
24.6.5.1 GDB User Interface Layout 271
24.6.5.2 Source Buffers 271
24.6.5.3 Breakpoints Buffer 272
24.6.5.4 Threads Buffer 272
24.6.5.5 Stack Buffer 273
24.6.5.6 Other GDB Buffers 273
24.6.5.7 Watch Expressions 274
24.6.5.8 Multithreaded Debugging 275
24.7 Executing Lisp Expressions 276
24.8 Libraries of Lisp Code for Emacs 276
24.9 Evaluating Emacs Lisp Expressions 278
24.10 Lisp Interaction Buffers 279
24.11 Running an External Lisp 279
25 Maintaining Large Programs 281
25.1 Version Control 281
25.1.1 Introduction to Version Control 281
25.1.1.1 Understanding the problems it addresses 281
25.1.1.2 Supported Version Control Systems 281
25.1.1.3 Concepts of Version Control 282
25.1.1.4 Merge-based vs lock-based Version Control 283
25.1.1.5 Changeset-based vs File-based Version Control ... . 283
25.1.1.6 Decentralized vs Centralized Repositories 284
25.1.1.7 Types of Log File 284
25.1.2 Version Control and the Mode Line 284
25.1.3 Basic Editing under Version Control 285
25.1.3.1 Basic Version Control with Merging 285
25.1.3.2 Basic Version Control with Locking 286
25.1.3.3 Advanced Control in C-x v v 287
25.1.4 Features of the Log Entry Buffer 287
xii
25.1.5 Registering a File for Version Control 288
25.1.6 Examining And Comparing Old Revisions 289
25.1.7 VC Change Log 290
25.1.8 Undoing Version Control Actions 292
25.1.9 Ignore Version Control Files 292
25.1.10 VC Directory Mode 292
25.1.10.1 The VC Directory Buffer 293
25.1.10.2 VC Directory Commands 293
25.1.11 Version Control Branches 295
25.1.11.1 Switching between Branches 295
25.1.11.2 Pulling Changes into a Branch 296
25.1.11.3 Merging Branches 296
25.1.11.4 Creating New Branches 297
25.2 Change Logs 297
25.2.1 Change Log Commands 297
25.2.2 Format of ChangeLog 298
25.3 Tags Tables 299
25.3.1 Source File Tag Syntax 299
25.3.2 Creating Tags Tables 301
25.3.3 Etags Regexps 302
25.3.4 Selecting a Tags Table 304
25.3.5 Finding a Tag 304
25.3.6 Searching and Replacing with Tags Tables 306
25.3.7 Tags Table Inquiries 307
25.4 Emacs Development Environment 307
26 Abbrevs 309
26.1 Abbrev Concepts 309
26.2 Defining Abbrevs 309
26.3 Controlling Abbrev Expansion 310
26.4 Examining and Editing Abbrevs 311
26.5 Saving Abbrevs 312
26.6 Dynamic Abbrev Expansion 313
26.7 Customizing Dynamic Abbreviation 314
27 Dired, the Directory Editor 315
27.1 Entering Dired 315
27.2 Navigation in the Dired Buffer 316
27.3 Deleting Files with Dired 316
27.4 Flagging Many Files at Once 317
27.5 Visiting Files in Dired 318
27.6 Dired Marks vs. Flags 318
27.7 Operating on Files 320
27.8 Shell Commands in Dired 322
27.9 Transforming File Names in Dired 323
27.10 File Comparison with Dired 324
27.11 Subdirectories in Dired 325
27.12 Moving Over Subdirectories 325
xiii
27.13 Hiding Subdirectories 326
27.14 Updating the Dired Buffer 326
27.15 Dired and find 327
27.16 Editing the Dired Buffer 328
27.17 Viewing Image Thumbnails in Dired 328
27.18 Other Dired Features 329
28 The Calendar and the Diary 331
28.1 Movement in the Calendar 331
28.1.1 Motion by Standard Lengths of Time 331
28.1.2 Beginning or End of Week, Month or Year 332
28.1.3 Specified Dates 332
28.2 Scrolling in the Calendar 333
28.3 Counting Days 333
28.4 Miscellaneous Calendar Commands 333
28.5 Writing Calendar Files 334
28.6 Holidays 335
28.7 Times of Sunrise and Sunset 336
28.8 Phases of the Moon 337
28.9 Conversion To and From Other Calendars 338
28.9.1 Supported Calendar Systems 338
28.9.2 Converting To Other Calendars 339
28.9.3 Converting From Other Calendars 340
28.10 The Diary 341
28.10.1 Displaying the Diary 341
28.10.2 The Diary File 342
28.10.3 Date Formats 343
28.10.4 Commands to Add to the Diary 344
28.10.5 Special Diary Entries 344
28.11 Appointments 346
28.12 Importing and Exporting Diary Entries 347
28.13 Daylight Saving Time 347
28.14 Summing Time Intervals 348
29 Sending Mail 350
29.1 The Format of the Mail Buffer 350
29.2 Mail Header Fields 351
29.3 Mail Aliases 352
29.4 Mail Commands 353
29.4.1 Mail Sending 353
29.4.2 Mail Header Editing 354
29.4.3 Citing Mail 355
29.4.4 Mail Miscellany 356
29.5 Mail Signature 356
29.6 Mail Amusements 357
29.7 Mail-Composition Methods 357
xiv
30 Reading Mail with Rmail 359
30.1 Basic Concepts of Rmail 359
30.2 Scrolling Within a Message 359
30.3 Moving Among Messages 360
30.4 Deleting Messages 361
30.5 Rmail Files and Inboxes 362
30.6 Multiple Rmail Files 363
30.7 Copying Messages Out to Files 364
30.8 Labels 365
30.9 Rmail Attributes 366
30.10 Sending Replies 367
30.11 Summaries 369
30.11.1 Making Summaries 369
30.11.2 Editing in Summaries 370
30.12 Sorting the Rmail File 372
30.13 Display of Messages 373
30.14 Rmail and Coding Systems 374
30.15 Editing Within a Message 374
30.16 Digest Messages 375
30.17 Reading Rot 13 Messages 375
30.18 movemail program 375
30.19 Retrieving Mail from Remote Mailboxes 377
30.20 Retrieving Mail from Local Mailboxes in Various Formats . . 378
31 Miscellaneous Commands 379
31.1 Gnus 379
31.1.1 Gnus Buffers 379
31.1.2 When Gnus Starts Up 379
31.1.3 Using the Gnus Group Buffer 380
31.1.4 Using the Gnus Summary Buffer 380
31.2 Document Viewing 381
31.2.1 DocView Navigation 381
31.2.2 DocView Searching 382
31.2.3 DocView Slicing 382
31.2.4 DocView Conversion 382
31.3 Web Browsing with EWW 383
31.4 Running Shell Commands from Emacs 383
31.4.1 Single Shell Commands 383
31.4.2 Interactive Subshell 384
31.4.3 Shell Mode 385
31.4.4 Shell Prompts 387
31.4.5 Shell Command History 388
31.4.5.1 Shell History Ring 388
31.4.5.2 Shell History Copying 389
31.4.5.3 Shell History References 390
31.4.6 Directory Tracking 390
31.4.7 Shell Mode Options 390
31.4.8 Emacs Terminal Emulator 391
XV
31.4.9 Term Mode 392
31.4.10 Remote Host Shell 393
31.4.11 Serial Terminal 393
31.5 Using Emacs as a Server 393
31.5.1 Invoking emacsclient 394
31.5.2 emacsclient Options 395
31.6 Printing Hard Copies 397
31.6.1 PostScript Hardcopy 398
31.6.2 Variables for PostScript Hardcopy 399
31.6.3 Printing Package 400
31.7 Sorting Text 400
31.8 Editing Binary Files 402
31.9 Saving Emacs Sessions 403
31.10 Recursive Editing Levels 404
31.11 Hyperlinking and Navigation Features 405
31.11.1 Following URLs 405
31.11.2 Activating URLs 405
31.11.3 Finding Files and URLs at Point 405
31.12 Other Amusements 406
32 Emacs Lisp Packages 408
32.1 The Package Menu Buffer 408
32.2 Package Installation 409
32.3 Package Files and Directory Layout 411
33 Customization 412
33.1 Easy Customization Interface 412
33.1.1 Customization Groups 412
33.1.2 Browsing and Searching for Settings 413
33.1.3 Changing a Variable 413
33.1.4 Saving Customizations 416
33.1.5 Customizing Faces 416
33.1.6 Customizing Specific Items 417
33.1.7 Custom Themes 418
33.1.8 Creating Custom Themes 419
33.2 Variables 420
33.2.1 Examining and Setting Variables 421
33.2.2 Hooks 422
33.2.3 Local Variables 423
33.2.4 Local Variables in Files 424
33.2.4.1 Specifying File Variables 424
33.2.4.2 Safety of File Variables 426
33.2.5 Per-Directory Local Variables 427
33.3 Customizing Key Bindings 428
33.3.1 Keymaps 429
33.3.2 Prefix Keymaps 429
33.3.3 Local Keymaps 430
33.3.4 Minibuffer Keymaps 430
33.3.5 Changing Key Bindings Interactively 431
33.3.6 Rebinding Keys in Your Init File 432
33.3.7 Modifier Keys 433
33.3.8 Rebinding Function Keys 433
33.3.9 Named ASCII Control Characters 434
33.3.10 Rebinding Mouse Buttons 435
33.3.11 Disabling Commands 437
33.4 The Emacs Initialization File 437
33.4.1 Init File Syntax 438
33.4.2 Init File Examples 439
33.4.3 Terminal-specific Initialization 441
33.4.4 How Emacs Finds Your Init File 442
33.4.5 Non-ASCII Characters in Init Files 442
34 Dealing with Common Problems 443
34.1 Quitting and Aborting 443
34.2 Dealing with Emacs Trouble 444
34.2.1 If DEL Fails to Delete 444
34.2.2 Recursive Editing Levels 445
34.2.3 Garbage on the Screen 445
34.2.4 Garbage in the Text 446
34.2.5 Running out of Memory 446
34.2.6 When Emacs Crashes 446
34.2.7 Recovery After a Crash 447
34.2.8 Emergency Escape 448
34.3 Reporting Bugs 448
34.3.1 Reading Existing Bug Reports and Known Problems . . . 448
34.3.2 When Is There a Bug 449
34.3.3 Understanding Bug Reporting 450
34.3.4 Checklist for Bug Reports 451
34.3.5 Sending Patches for GNU Emacs 456
34.4 Contributing to Emacs Development 457
34.5 How To Get Help with GNU Emacs 457
Appendix A GNU GENERAL PUBLIC
LICENSE 459
Appendix B GNU Free Documentation License 470
Appendix C Command Line Arguments for
Emacs Invocation 478
C.l Action Arguments 478
C.2 Initial Options 480
C.3 Command Argument Example 482
C.4 Environment Variables 482
C.4.1 General Variables 483
C.4. 2 Miscellaneous Variables 485
C. 4.3 The MS-Windows System Registry 486
C.5 Specifying the Display Name 487
C.6 Font Specification Options 487
C.7 Window Color Options 488
C.8 Options for Window Size and Position 489
C.9 Internal and External Borders 490
C.10 Frame Titles 491
Oil Icons 491
C. 12 Other Display Options 492
Appendix D X Options and Resources 493
D. l X Resources 493
D.2 Table of X Resources for Emacs 494
D.3 GTK resources 495
D. 3.1 GTK Resource Basics 496
D.3. 2 GTK widget names 496
D.3. 3 GTK Widget Names in Emacs 497
D.3.4 GTK styles 498
Appendix E Emacs 23 Antinews 500
Appendix F Emacs and Mac OS / GNUstep
502
F.l Basic Emacs usage under Mac OS and GNUstep 502
F.l.l Grabbing environment variables 502
F.2 Mac / GNUstep Customization 503
F.2.1 Font and Color Panels 503
F.3 Windowing System Events under Mac OS / GNUstep 503
F.4 GNUstep Support 504
Appendix G Emacs and Microsoft
Windows/MS-DOS 505
G.l How to Start Emacs on MS-Windows 505
G.2 Text Files and Binary Files 506
G.3 File Names on MS-Windows 507
G.4 Emulation of Is on MS-Windows 508
G.5 HOME and Startup Directories on MS-Windows 508
G.6 Keyboard Usage on MS-Windows 509
G.7 Mouse Usage on MS-Windows 509
G.8 Subprocesses on Windows 9X/ME and Windows NT/2K/XP
510
G.9 Printing and MS-Windows 511
G.10 Specifying Fonts on MS-Windows 512
G.ll Miscellaneous Windows-specific features 514
The GNU Manifesto 515
What's GNU? Gnu's Not Unix! 515
Why I Must Write GNU 516
Why GNU Will Be Compatible with Unix 516
How GNU Will Be Available 516
Why Many Other Programmers Want to Help 516
How You Can Contribute 517
Why All Computer Users Will Benefit 517
Some Easily Rebutted Objections to GNU's Goals 518
Glossary 523
Key (Character) Index 546
Command and Function Index 555
Variable Index 568
Concept Index 575
Preface
1
Preface
This manual documents the use and simple customization of the Emacs editor. Simple Emacs customizations do not require you to be a programmer, but if you are not interested in customizing, you can ignore the customization hints.
This is primarily a reference manual, but can also be used as a primer. If you are new to Emacs, we recommend you start with the integrated, learn-by-doing tutorial, before reading the manual. To run the tutorial, start Emacs and type C-h t. The tutorial describes commands, tells you when to try them, and explains the results. The tutorial is available in several languages.
On first reading, just skim chapters 1 and 2, which describe the notational conventions of the manual and the general appearance of the Emacs display screen. Note which questions are answered in these chapters, so you can refer back later. After reading chapter 4, you should practice the commands shown there. The next few chapters describe fundamental techniques and concepts that are used constantly. You need to understand them thoroughly, so experiment with them until you are fluent.
Chapters 14 through 19 describe intermediate-level features that are useful for many kinds of editing. Chapter 20 and following chapters describe optional but useful features; read those chapters when you need them.
Read the Common Problems chapter if Emacs does not seem to be working properly. It explains how to cope with several common problems (see Section 34.2 [Dealing with Emacs Trouble], page 444), as well as when and how to report Emacs bugs (see Section 34.3 [Bugs], page 448).
To find the documentation of a particular command, look in the index. Keys (character commands) and command names have separate indexes. There is also a glossary, with a cross reference for each term.
This manual is available as a printed book and also as an Info file. The Info file is for reading from Emacs itself, or with the Info program. Info is the principal format for documentation in the GNU system. The Info file and the printed book contain substantially the same text and are generated from the same source files, which are also distributed with GNU Emacs.
GNU Emacs is a member of the Emacs editor family. There are many Emacs editors, all sharing common principles of organization. For information on the underlying philos- ophy of Emacs and the lessons learned from its development, see Emacs, the Extensible, Customizable Self-Documenting Display Editor, available from ftp : //publications . ai . mit . edu/ai-publications/pdf /AIM-519A.pdf .
This version of the manual is mainly intended for use with GNU Emacs installed on GNU and Unix systems. GNU Emacs can also be used on MS-DOS, Microsoft Windows, and Macintosh systems. The Info file version of this manual contains some more information about using Emacs on those systems. Those systems use different file name syntax; in addition MS-DOS does not support all GNU Emacs features. See Appendix G [Microsoft Windows], page 505, for information about using Emacs on Windows. See Appendix F [Mac OS / GNUstep], page 502, for information about using Emacs on Macintosh (and GNUstep).
Distribution
2
Distribution
GNU Emacs is free software; this means that everyone is free to use it and free to redistribute it under certain conditions. GNU Emacs is not in the public domain; it is copyrighted and there are restrictions on its distribution, but these restrictions are designed to permit everything that a good cooperating citizen would want to do. What is not allowed is to try to prevent others from further sharing any version of GNU Emacs that they might get from you. The precise conditions are found in the GNU General Public License that comes with Emacs and also appears in this manual1. See Appendix A [Copying], page 459.
One way to get a copy of GNU Emacs is from someone else who has it. You need not ask for our permission to do so, or tell any one else; just copy it. If you have access to the Internet, you can get the latest distribution version of GNU Emacs by anonymous FTP; see http://www.gnu.org/software/emacs on our website for more information.
You may also receive GNU Emacs when you buy a computer. Computer manufacturers are free to distribute copies on the same terms that apply to everyone else. These terms require them to give you the full sources, including whatever changes they may have made, and to permit you to redistribute the GNU Emacs received from them under the usual terms of the General Public License. In other words, the program must be free for you when you get it, not just free for the manufacturer.
If you find GNU Emacs useful, please send a donation to the Free Software Foundation to support our work. Donations to the Free Software Foundation are tax deductible in the US. If you use GNU Emacs at your workplace, please suggest that the company make a donation. To donate, see https : //my . f sf . org/donate/. For other ways in which you can help, see http://www.gnu.org/help/help.html.
We also sell hardcopy versions of this manual and An Introduction to Programming in Emacs Lisp, by Robert J. Chassell. You can visit our online store at http://shop.fsf . org/. The income from sales goes to support the foundation's purpose: the development of new free software, and improvements to our existing programs including GNU Emacs.
If you need to contact the Free Software Foundation, see http://www.fsf .org/about/ contact/, or write to
Free Software Foundation 51 Franklin Street, Fifth Floor Boston, MA 02110-1301 USA
Acknowledgments
Contributors to GNU Emacs include Jari Aalto, Per Abrahamsen, Tomas Abrahamsson, Jay K. Adams, Alon Albert, Michael Albinus, Nagy Andras, Benjamin Andresen, Ralf An- geli, Dmitry Antipov, Joe Arceneaux, Emil Astrom, Miles Bader, David Bakhash, Juanma Barranquero, Eli Barzilay, Thomas Baumann, Steven L. Baur, Jay Belanger, Alexander L. Belikoff, Thomas Bellman, Scott Bender, Boaz Ben-Zvi, Sergey Berezin, Stephen Berman,
1 This manual is itself covered by the GNU Free Documentation License. This license is similar in spirit to the General Public License, but is more suitable for documentation. See Appendix B [GNU Free Documentation License] , page 470.
Distribution
3
Karl Berry, Anna M. Bigatti, Ray Blaak, Martin Blais, Jim Blandy, Johan Bockgard, Jan Bocker, Joel Boehland, Lennart Borgman, Per Bothner, Terrence Brannon, Frank Bresz, Peter Breton, Emmanuel Briot, Kevin Broadey, Vincent Broman, Michael Brouwer, David M. Brown, Stefan Bruda, Georges Brun-Cottan, Joe Buehler, Scott Byer, Wlodek Bzyl, Bill Carpenter, Per Cederqvist, Hans Chalupsky, Chris Chase, Bob Chassell, An- drew Choi, Chong Yidong, Sacha Chua, Stewart Clamen, James Clark, Mike Clarkson, Glynn Clements, Andrew Cohen, Daniel Colascione, Christoph Conrad, Ludovic Courtes, Andrew Csillag, Toby Cubitt, Baoqiu Cui, Doug Cutting, Mathias Dahl, Julien Danjou, Satyaki Das, Vivek Dasmohapatra, Dan Davison, Michael DeCorte, Gary Delp, Nachum Dershowitz, Dave Detlefs, Matthieu Devin, Christophe de Dinechin, Eri Ding, Jan Djarv, Lawrence R. Dodd, Carsten Dominik, Scott Draves, Benjamin Drieu, Viktor Dukhovni, Jacques Duthen, Dmitry Dzhus, John Eaton, Rolf Ebert, Carl Edman, David Edmondson, Paul Eggert, Stephen Eglen, Christian Egli, Torbjorn Einarsson, Tsugutomo Enami, David Engster, Hans Henrik Eriksen, Michael Ernst, Ata Etemadi, Frederick Farnbach, Oscar Figueiredo, Fred Fish, Steve Fisk, Karl Fogel, Gary Foster, Eric S. Fraga, Romain Francoise, Noah Friedman, Andreas Fuchs, Shigeru Fukaya, Xue Fuqiao, Hallvard Furuseth, Keith Gabryelski, Peter S. Galbraith, Kevin Gallagher, Fabian E. Gallina, Kevin Gallo, Juan Leon Lahoz Garcia, Howard Gayle, Daniel German, Stephen Gildea, Julien Gilles, David Gillespie, Bob Glickstein, Deepak Goel, David De La Harpe Golden, Boris Goldowsky, David Goodger, Chris Gray, Kevin Greiner, Michelangelo Grigni, Odd Gripenstam, Kai Grofijohann, Michael Gschwind, Bastien Guerry, Henry Guillaume, Dmitry Gutov, Doug Gwyn, Bruno Haible, Ken'ichi Handa, Lars Hansen, Chris Hanson, Jesper Harder, Alexan- dra Harsanyi, K. Shane Hartman, John Heidemann, Jon K. Hellan, Magnus Henoch, Markus Heritsch, Dirk Herrmann, Karl Heuer, Manabu Higashida, Konrad Hinsen, Anders Hoist, Jeffrey C. Honig, Tassilo Horn, Kurt Hornik, Tom Houlder, Joakim Hove, Denis Howe, Lars Ingebrigtsen, Andrew Innes, Seiichiro Inoue, Philip Jackson, Martyn Jago, Pavel Janik, Paul Jarc, Ulf Jasper, Thorsten Jolitz, Michael K. Johnson, Kyle Jones, Terry Jones, Si- mon Josefsson, Alexandre Julliard, Arne J0rgensen, Tomoji Kagatani, Brewster Kahle, Tokuya Kameshima, Lute Kamstra, Ivan Kanis, David Kastrup, David Kaufman, Henry Kautz, Taichi Kawabata, Taro Kawagishi, Howard Kaye, Michael Kifer, Richard King, Pe- ter Kleiweg, Karel Khc, Shuhei Kobayashi, Pavel Kobyakov, Larry K. Kolodney, David M. Koppelman, Koseki Yoshinori, Robert Krawitz, Sebastian Kremer, Ryszard Kubiak, Igor Kuzmin, David Kagedal, Daniel LaLiberte, Karl Landstrom, Mario Lang, Aaron Larson, James R. Larus, Vinicius Jose Latorre, Werner Lemberg, Frederic Lepied, Peter Liljenberg, Christian Limpach, Lars Lindberg, Chris Lindblad, Anders Lindgren, Thomas Link, Juri Linkov, Francis Litterio, Sergey Litvinov, Leo Liu, Emilio C. Lopes, Martin Lorentzon, Dave Love, Eric Ludlam, Karoly Lorentey, Sascha Liidecke, Greg McGary, Roland Mc- Grath, Michael McNamara, Alan Mackenzie, Christopher J. Madsen, Neil M. Mager, Ken Manheimer, Bill Mann, Brian Marick, Simon Marshall, Bengt Martensson, Charlie Martin, Yukihiro Matsumoto, Tomohiro Matsuyama, David Maus, Thomas May, Will Mengarini, David Megginson, Stefan Merten, Ben A. Mesander, Wayne Mesard, Brad Miller, Lawrence Mitchell, Richard Mlynarik, Gerd Mollmann, Dani Moncayo, Stefan Monnier, Keith Moore, Jan Moringen, Morioka Tomohiko, Glenn Morris, Don Morrison, Diane Murray, Riccardo Murri, Sen Nagata, Erik Naggum, Gergely Nagy, Nobuyoshi Nakada, Thomas Neumann, Mike Newton, Thien-Thi Nguyen, Jurgen Nickelsen, Dan Nicolaescu, Hrvoje Niksic, Jeff Norden, Andrew Norman, Edward O'Connor, Kentaro Ohkouchi, Christian Ohler, Kenichi Okada, Alexandre Oliva, Bob Olson, Michael Olson, Takaaki Ota, Pieter E. J. Pareit, Ross
Distribution
4
Patterson, David Pearson, Juan Pechiar, Jeff Peck, Damon Anton Permezel, Tom Per- rine, William M. Perry, Per Persson, Jens Petersen, Daniel Pfeiffer, Justus Piater, Richard L. Pieri, Fred Pierresteguy, Francois Pinard, Daniel Pittman, Christian Plaunt, Alexan- der Pohoyda, David Ponce, Francesco A. Potorti, Michael D. Prange, Mukesh Prasad, Ken Raeburn, Marko Rahamaa, Ashwin Ram, Eric S. Raymond, Paul Reilly, Edward M. Reingold, David Reitter, Alex Rezinsky, Rob Riepel, Lara Rios, Adrian Robert, Nick Roberts, Roland B. Roberts, John Robinson, Denis B. Roegel, Danny Roozendaal, Sebas- tian Rose, William Rosenblatt, Markus Rost, Guillermo J. Rozas, Martin Rudalics, Ivar Rummelhoff, Jason Rumney, Wolfgang Rupprecht, Benjamin Rutt, Kevin Ryde, James B. Salem, Masahiko Sato, Timo Savola, Jorgen Schafer, Holger Schauer, William Schelter, Ralph Schleicher, Gregor Schmid, Michael Schmidt, Ronald S. Schnell, Philippe Schnoebe- len, Jan Schormann, Alex Schroeder, Stefan Schoef, Rainer Schopf, Raymond Scholz, Eric Schulte, Andreas Schwab, Randal Schwartz, Oliver Seidel, Manuel Serrano, Paul Sexton, Hovav Shacham, Stanislav Shalunov, Marc Shapiro, Richard Sharman, Olin Shivers, Tibor Simko, Espen Skoglund, Rick Sladkey, Lynn Slater, Chris Smith, David Smith, Paul D. Smith, Wilson Snyder, William Sommerfeld, Simon South, Andre Spiegel, Michael Staats, Thomas Steffen, Ulf Stegemann, Reiner Steib, Sam Steingold, Ake Stenhoff, Peter Stephen- son, Ken Stevens, Andy Stewart, Jonathan Stigelman, Martin Stjernholm, Kim F. Storm, Steve Strassmann, Christopher Suckling, Olaf Sylvester, Naoto Takahashi, Steven Tamm, Jan Tatarik, Luc Teirlinck, Jean-Philippe Theberge, Jens T. Berger Thielemann, Spencer Thomas, Jim Thompson, Toru Tomabechi, David O'Toole, Markus Triska, Tom Tromey, Enami Tsugutomo, Eli Tziperman, Daiki Ueno, Masanobu Umeda, Rajesh Vaidheeswar- ran, Neil W. Van Dyke, Didier Verna, Joakim Verona, Ulrik Vieth, Geoffrey Voelker, Johan Vromans, Inge Wallin, John Paul Wallington, Colin Walters, Barry Warsaw, Christoph Wedler, Ilja Weis, Zhang Weize, Morten Welinder, Joseph Brian Wells, Rodney Whitby, John Wiegley, Sascha Wilde, Ed Wilkinson, Mike Williams, Roland Winkler, Bill Wohler, Steven A. Wood, Dale R. Worley, Francis J. Wright, Felix S. T. Wu, Tom Wurgler, Ya- mamoto Mitsuharu, Katsumi Yamaoka, Masatake Yamato, Jonathan Yavner, Ryan Yeske, Ilya Zakharevich, Milan Zamazal, Victor Zandy, Eli Zaretskii, Jamie Zawinski, Andrew Zhilin, Shenghuo Zhu, Piotr Zielihski, Ian T. Zimmermann, Reto Zimmermann, Neal Zir- ing, Teodor Zlatanov, and Detlev Zundel.
Introduction
5
Introduction
You are reading about GNU Emacs, the GNU incarnation of the advanced, self- documenting, customizable, extensible editor Emacs. (The 'G' in GNU (GNU's Not Unix) is not silent.)
We call Emacs advanced because it can do much more than simple insertion and deletion of text. It can control subprocesses, indent programs automatically, show multiple files at once, and more. Emacs editing commands operate in terms of characters, words, lines, sen- tences, paragraphs, and pages, as well as expressions and comments in various programming languages.
Self-documenting means that at any time you can use special commands, known as help commands, to find out what your options are, or to find out what any command does, or to find all the commands that pertain to a given topic. See Chapter 7 [Help], page 37.
Customizable means that you can easily alter the behavior of Emacs commands in simple ways. For instance, if you use a programming language in which comments start with '<**' and end with '**>', you can tell the Emacs comment manipulation commands to use those strings (see Section 23.5 [Comments], page 249). To take another example, you can rebind the basic cursor motion commands (up, down, left and right) to any keys on the keyboard that you find comfortable. See Chapter 33 [Customization], page 412.
Extensible means that you can go beyond simple customization and create entirely new commands. New commands are simply programs written in the Lisp language, which are run by Emacs's own Lisp interpreter. Existing commands can even be redefined in the middle of an editing session, without having to restart Emacs. Most of the editing commands in Emacs are written in Lisp; the few exceptions could have been written in Lisp but use C instead for efficiency. Writing an extension is programming, but non-programmers can use it afterwards. See Section "Preface" in An Introduction to Programming in Emacs Lisp, if you want to learn Emacs Lisp programming.
Chapter 1: The Organization of the Screen
6
1 The Organization of the Screen
On a graphical display, such as on GNU /Linux using the X Window System, Emacs occupies a "graphical window" . On a text terminal, Emacs occupies the entire terminal screen. We will use the term frame to mean a graphical window or terminal screen occupied by Emacs. Emacs behaves very similarly on both kinds of frames. It normally starts out with just one frame, but you can create additional frames if you wish (see Chapter 18 [Frames], page 162).
Each frame consists of several distinct regions. At the top of the frame is a menu bar, which allows you to access commands via a series of menus. On a graphical display, directly below the menu bar is a tool bar, a row of icons that perform editing commands if you click on them. At the very bottom of the frame is an echo area, where informative messages are displayed and where you enter information when Emacs asks for it.
The main area of the frame, below the tool bar (if one exists) and above the echo area, is called the window. Henceforth in this manual, we will use the word "window" in this sense. Graphical display systems commonly use the word "window" with a different meaning; but, as stated above, we refer to those "graphical windows" as "frames" .
An Emacs window is where the buffer — the text you are editing — is displayed. On a graphical display, the window possesses a scroll bar on one side, which can be used to scroll through the buffer. The last line of the window is a mode line. This displays various information about what is going on in the buffer, such as whether there are unsaved changes, the editing modes that are in use, the current line number, and so forth.
When you start Emacs, there is normally only one window in the frame. However, you can subdivide this window horizontally or vertically to create multiple windows, each of which can independently display a buffer (see Chapter 17 [Windows], page 156).
At any time, one window is the selected window. On a graphical display, the selected window shows a more prominent cursor (usually solid and blinking); other windows show a less prominent cursor (usually a hollow box). On a text terminal, there is only one cursor, which is shown in the selected window. The buffer displayed in the selected window is called the current buffer, and it is where editing happens. Most Emacs commands implicitly apply to the current buffer; the text displayed in unselected windows is mostly visible for reference. If you use multiple frames on a graphical display, selecting a particular frame selects a window in that frame.
1.1 Point
The cursor in the selected window shows the location where most editing commands take effect, which is called point1. Many Emacs commands move point to different places in the buffer; for example, you can place point by clicking mouse button 1 (normally the left button) at the desired location.
By default, the cursor in the selected window is drawn as a solid block and appears to be on a character, but you should think of point as between two characters; it is situated before the character under the cursor. For example, if