Table of Contents ***************** The Emacs Editor Distribution Introduction 1 The Organization of the Screen 1.1 Point 1.2 The Echo Area 1.3 The Mode Line 1.4 The Menu Bar 2 Kinds of User Input 3 Keys 4 Keys and Commands 5 Character Set for Text 6 Entering and Exiting Emacs 7 Exiting Emacs 8 Basic Editing Commands 8.1 Inserting Text 8.2 Changing the Location of Point 8.3 Erasing Text 8.4 Undoing Changes 8.5 Files 8.6 Help 8.7 Blank Lines 8.8 Continuation Lines 8.9 Cursor Position Information 8.10 Numeric Arguments 8.11 Repeating a Command 9 The Minibuffer 9.1 Minibuffers for File Names 9.2 Editing in the Minibuffer 9.3 Completion 9.3.1 Completion Example 9.3.2 Completion Commands 9.3.3 Strict Completion 9.3.4 Completion Options 9.4 Minibuffer History 9.5 Repeating Minibuffer Commands 10 Running Commands by Name 11 Help 11.1 Help Summary 11.2 Documentation for a Key 11.3 Help by Command or Variable Name 11.4 Apropos 11.5 Help Mode Commands 11.6 Keyword Search for Lisp Libraries 11.7 Help for International Language Support 11.8 Other Help Commands 11.9 Help Files 11.10 Help on Active Text and Tooltips 12 The Mark and the Region 12.1 Setting the Mark 12.2 Transient Mark Mode 12.3 Using Transient Mark Mode Momentarily 12.4 Operating on the Region 12.5 Commands to Mark Textual Objects 12.6 The Mark Ring 12.7 The Global Mark Ring 13 Killing and Moving Text 13.1 Deletion 13.2 Killing by Lines 13.3 Other Kill Commands 14 Yanking 14.1 The Kill Ring 14.2 Appending Kills 14.3 Yanking Earlier Kills 15 Accumulating Text 16 Rectangles 17 CUA Bindings 18 Registers 18.1 Saving Positions in Registers 18.2 Saving Text in Registers 18.3 Saving Rectangles in Registers 18.4 Saving Window Configurations in Registers 18.5 Keeping Numbers in Registers 18.6 Keeping File Names in Registers 18.7 Bookmarks 19 Controlling the Display 19.1 Scrolling 19.2 Automatic Scrolling 19.3 Horizontal Scrolling 19.4 Follow Mode 19.5 Using Multiple Typefaces 19.6 Standard Faces 19.7 Font Lock mode 19.8 Interactive Highlighting 19.9 Window Fringes 19.10 Displaying Boundaries 19.11 Useless Whitespace 19.12 Selective Display 19.13 Optional Mode Line Features 19.14 How Text Is Displayed 19.15 Displaying the Cursor 19.16 Truncation of Lines 19.17 Customization of Display 20 Searching and Replacement 20.1 Incremental Search 20.1.1 Basics of Incremental Search 20.1.2 Repeating Incremental Search 20.1.3 Errors in Incremental Search 20.1.4 Special Input for Incremental Search 20.1.5 Isearch for Non-ASCII Characters 20.1.6 Isearch Yanking 20.1.7 Lazy Search Highlighting 20.1.8 Scrolling During Incremental Search 20.1.9 Slow Terminal Incremental Search 20.2 Nonincremental Search 20.3 Word Search 20.4 Regular Expression Search 20.5 Syntax of Regular Expressions 20.6 Backslash in Regular Expressions 20.7 Regular Expression Example 20.8 Searching and Case 20.9 Replacement Commands 20.9.1 Unconditional Replacement 20.9.2 Regexp Replacement 20.9.3 Replace Commands and Case 20.9.4 Query Replace 20.10 Other Search-and-Loop Commands 21 Commands for Fixing Typos 21.1 Undo 21.2 Killing Your Mistakes 21.3 Transposing Text 21.4 Case Conversion 21.5 Checking and Correcting Spelling 22 Keyboard Macros 22.1 Basic Use 22.2 The Keyboard Macro Ring 22.3 The Keyboard Macro Counter 22.4 Executing Macros with Variations 22.5 Naming and Saving Keyboard Macros 22.6 Editing a Keyboard Macro 22.7 Stepwise Editing a Keyboard Macro 23 File Handling 23.1 File Names 23.2 Visiting Files 23.3 Saving Files 23.3.1 Commands for Saving Files 23.3.2 Backup Files 23.3.2.1 Numbered Backups 23.3.2.2 Single or Numbered Backups 23.3.2.3 Automatic Deletion of Backups 23.3.2.4 Copying vs. Renaming 23.3.3 Customizing Saving of Files 23.3.4 Protection against Simultaneous Editing 23.3.5 Shadowing Files 23.3.6 Updating Time Stamps Automatically 23.4 Reverting a Buffer 23.5 Auto Reverting non-file Buffers 23.5.1 Auto Reverting the Buffer Menu 23.5.2 Auto Reverting Dired buffers 23.5.3 Adding Support for Auto-Reverting additional Buffers. 23.6 Auto-Saving: Protection Against Disasters 23.6.1 Auto-Save Files 23.6.2 Controlling Auto-Saving 23.6.3 Recovering Data from Auto-Saves 23.7 File Name Aliases 23.8 Version Control 23.8.1 Introduction to Version Control 23.8.1.1 Supported Version Control Systems 23.8.1.2 Concepts of Version Control 23.8.1.3 Types of Log File 23.8.2 Version Control and the Mode Line 23.8.3 Basic Editing under Version Control 23.8.3.1 Basic Version Control with Locking 23.8.3.2 Basic Version Control without Locking 23.8.3.3 Advanced Control in `C-x v v' 23.8.3.4 Features of the Log Entry Buffer 23.8.4 Examining And Comparing Old Versions 23.8.5 The Secondary Commands of VC 23.8.5.1 Registering a File for Version Control 23.8.5.2 VC Status Commands 23.8.5.3 Undoing Version Control Actions 23.8.5.4 Dired under VC 23.8.5.5 VC Dired Commands 23.8.6 Multiple Branches of a File 23.8.6.1 Switching between Branches 23.8.6.2 Creating New Branches 23.8.6.3 Merging Branches 23.8.6.4 Multi-User Branching 23.8.7 Remote Repositories 23.8.7.1 Version Backups 23.8.7.2 Local Version Control 23.8.8 Snapshots 23.8.8.1 Making and Using Snapshots 23.8.8.2 Snapshot Caveats 23.8.9 Miscellaneous Commands and Features of VC 23.8.9.1 Change Logs and VC 23.8.9.2 Renaming VC Work Files and Master Files 23.8.9.3 Inserting Version Control Headers 23.8.10 Customizing VC 23.8.10.1 General Options 23.8.10.2 Options for RCS and SCCS 23.8.10.3 Options specific for CVS 23.9 File Directories 23.10 Comparing Files 23.11 Diff Mode 23.12 Miscellaneous File Operations 23.13 Accessing Compressed Files 23.14 File Archives 23.15 Remote Files 23.16 Quoted File Names 23.17 File Name Cache 23.18 Convenience Features for Finding Files 23.19 Filesets 24 Using Multiple Buffers 24.1 Creating and Selecting Buffers 24.2 Listing Existing Buffers 24.3 Miscellaneous Buffer Operations 24.4 Killing Buffers 24.5 Operating on Several Buffers 24.6 Indirect Buffers 24.7 Convenience Features and Customization of Buffer Handling 24.7.1 Making Buffer Names Unique 24.7.2 Switching Between Buffers using Substrings 24.7.3 Customizing Buffer Menus 25 Multiple Windows 25.1 Concepts of Emacs Windows 25.2 Splitting Windows 25.3 Using Other Windows 25.4 Displaying in Another Window 25.5 Forcing Display in the Same Window 25.6 Deleting and Rearranging Windows 25.7 Window Handling Convenience Features and Customization 26 Frames and Graphical Displays 26.1 Killing and Yanking on Graphical Displays 26.1.1 Mouse Commands for Editing 26.1.2 Cut and Paste with Other Window Applications 26.1.3 Mouse Commands for Words and Lines 26.1.4 Secondary Selection 26.1.5 Using the Clipboard 26.2 Following References with the Mouse 26.3 Mouse Clicks for Menus 26.4 Mode Line Mouse Commands 26.5 Creating Frames 26.6 Frame Commands 26.7 Speedbar Frames 26.8 Multiple Displays 26.9 Special Buffer Frames 26.10 Setting Frame Parameters 26.11 Scroll Bars 26.12 Scrolling With "Wheeled" Mice 26.13 Drag and Drop 26.14 Menu Bars 26.15 Tool Bars 26.16 Using Dialog Boxes 26.17 Tooltips 26.18 Mouse Avoidance 26.19 Non-Window Terminals 26.20 Using a Mouse in Terminal Emulators 27 International Character Set Support 27.1 Introduction to International Character Sets 27.2 Enabling Multibyte Characters 27.3 Language Environments 27.4 Input Methods 27.5 Selecting an Input Method 27.6 Unibyte and Multibyte Non-ASCII characters 27.7 Coding Systems 27.8 Recognizing Coding Systems 27.9 Specifying a File's Coding System 27.10 Choosing Coding Systems for Output 27.11 Specifying a Coding System for File Text 27.12 Coding Systems for Interprocess Communication 27.13 Coding Systems for File Names 27.14 Coding Systems for Terminal I/O 27.15 Fontsets 27.16 Defining fontsets 27.17 Undisplayable Characters 27.18 Unibyte Editing Mode 27.19 Charsets 28 Major Modes 28.1 How Major Modes are Chosen 29 Indentation 29.1 Indentation Commands and Techniques 29.2 Tab Stops 29.3 Tabs vs. Spaces 30 Commands for Human Languages 30.1 Words 30.2 Sentences 30.3 Paragraphs 30.4 Pages 30.5 Filling Text 30.5.1 Auto Fill Mode 30.5.2 Explicit Fill Commands 30.5.3 The Fill Prefix 30.5.4 Adaptive Filling 30.5.5 Refill Mode 30.5.6 Long Lines Mode 30.6 Case Conversion Commands 30.7 Text Mode 30.8 Outline Mode 30.8.1 Format of Outlines 30.8.2 Outline Motion Commands 30.8.3 Outline Visibility Commands 30.8.4 Viewing One Outline in Multiple Views 30.8.5 Folding Editing 30.9 TeX Mode 30.9.1 TeX Editing Commands 30.9.2 LaTeX Editing Commands 30.9.3 TeX Printing Commands 30.9.4 TeX Mode Miscellany 30.10 SGML, XML, and HTML Modes 30.11 Nroff Mode 30.12 Editing Formatted Text 30.12.1 Requesting to Edit Formatted Text 30.12.2 Hard and Soft Newlines 30.12.3 Editing Format Information 30.12.4 Faces in Formatted Text 30.12.5 Colors in Formatted Text 30.12.6 Indentation in Formatted Text 30.12.7 Justification in Formatted Text 30.12.8 Setting Other Text Properties 30.12.9 Forcing Enriched Mode 30.13 Editing Text-based Tables 30.13.1 What is a Text-based Table? 30.13.2 How to Create a Table? 30.13.3 Table Recognition 30.13.4 Commands for Table Cells 30.13.5 Cell Justification 30.13.6 Commands for Table Rows 30.13.7 Commands for Table Columns 30.13.8 Fix Width of Cells 30.13.9 Conversion Between Plain Text and Tables 30.13.10 Analyzing Table Dimensions 30.13.11 Table Miscellany 31 Editing Programs 31.1 Major Modes for Programming Languages 31.2 Top-Level Definitions, or Defuns 31.2.1 Left Margin Convention 31.2.2 Moving by Defuns 31.2.3 Imenu 31.2.4 Which Function Mode 31.3 Indentation for Programs 31.3.1 Basic Program Indentation Commands 31.3.2 Indenting Several Lines 31.3.3 Customizing Lisp Indentation 31.3.4 Commands for C Indentation 31.3.5 Customizing C Indentation 31.4 Commands for Editing with Parentheses 31.4.1 Expressions with Balanced Parentheses 31.4.2 Moving in the Parenthesis Structure 31.4.3 Automatic Display Of Matching Parentheses 31.5 Manipulating Comments 31.5.1 Comment Commands 31.5.2 Multiple Lines of Comments 31.5.3 Options Controlling Comments 31.6 Documentation Lookup 31.6.1 Info Documentation Lookup 31.6.2 Man Page Lookup 31.6.3 Emacs Lisp Documentation Lookup 31.7 Hideshow minor mode 31.8 Completion for Symbol Names 31.9 Glasses minor mode 31.10 Other Features Useful for Editing Programs 31.11 C and Related Modes 31.11.1 C Mode Motion Commands 31.11.2 Electric C Characters 31.11.3 Hungry Delete Feature in C 31.11.4 Other Commands for C Mode 31.12 Asm Mode 31.13 Fortran Mode 31.13.1 Motion Commands 31.13.2 Fortran Indentation 31.13.2.1 Fortran Indentation and Filling Commands 31.13.2.2 Continuation Lines 31.13.2.3 Line Numbers 31.13.2.4 Syntactic Conventions 31.13.2.5 Variables for Fortran Indentation 31.13.3 Fortran Comments 31.13.4 Auto Fill in Fortran Mode 31.13.5 Checking Columns in Fortran 31.13.6 Fortran Keyword Abbrevs 32 Compiling and Testing Programs 32.1 Running Compilations under Emacs 32.2 Compilation Mode 32.3 Subshells for Compilation 32.4 Searching with Grep under Emacs 32.5 Finding Syntax Errors On The Fly 32.6 Running Debuggers Under Emacs 32.6.1 Starting GUD 32.6.2 Debugger Operation 32.6.3 Commands of GUD 32.6.4 GUD Customization 32.6.5 GDB Graphical Interface 32.6.5.1 GDB User Interface Layout 32.6.5.2 Source Buffers 32.6.5.3 Breakpoints Buffer 32.6.5.4 Stack Buffer 32.6.5.5 Other Buffers 32.6.5.6 Watch Expressions 32.7 Executing Lisp Expressions 32.8 Libraries of Lisp Code for Emacs 32.9 Evaluating Emacs Lisp Expressions 32.10 Lisp Interaction Buffers 32.11 Running an External Lisp 33 Maintaining Large Programs 33.1 Change Logs 33.2 Format of ChangeLog 33.3 Tags Tables 33.3.1 Source File Tag Syntax 33.3.2 Creating Tags Tables 33.3.3 Etags Regexps 33.3.4 Selecting a Tags Table 33.3.5 Finding a Tag 33.3.6 Searching and Replacing with Tags Tables 33.3.7 Tags Table Inquiries 33.4 Merging Files with Emerge 33.4.1 Overview of Emerge 33.4.2 Submodes of Emerge 33.4.3 State of a Difference 33.4.4 Merge Commands 33.4.5 Exiting Emerge 33.4.6 Combining the Two Versions 33.4.7 Fine Points of Emerge 34 Abbrevs 34.1 Abbrev Concepts 34.2 Defining Abbrevs 34.3 Controlling Abbrev Expansion 34.4 Examining and Editing Abbrevs 34.5 Saving Abbrevs 34.6 Dynamic Abbrev Expansion 34.7 Customizing Dynamic Abbreviation 35 Editing Pictures 35.1 Basic Editing in Picture Mode 35.2 Controlling Motion after Insert 35.3 Picture Mode Tabs 35.4 Picture Mode Rectangle Commands 36 Sending Mail 36.1 The Format of the Mail Buffer 36.2 Mail Header Fields 36.3 Mail Aliases 36.4 Mail Mode 36.4.1 Mail Sending 36.4.2 Mail Header Editing 36.4.3 Citing Mail 36.4.4 Mail Mode Miscellany 36.5 Mail Amusements 36.6 Mail-Composition Methods 37 Reading Mail with Rmail 37.1 Basic Concepts of Rmail 37.2 Scrolling Within a Message 37.3 Moving Among Messages 37.4 Deleting Messages 37.5 Rmail Files and Inboxes 37.6 Multiple Rmail Files 37.7 Copying Messages Out to Files 37.8 Labels 37.9 Rmail Attributes 37.10 Sending Replies 37.11 Summaries 37.11.1 Making Summaries 37.11.2 Editing in Summaries 37.12 Sorting the Rmail File 37.13 Display of Messages 37.14 Rmail and Coding Systems 37.15 Editing Within a Message 37.16 Digest Messages 37.17 Converting an Rmail File to Inbox Format 37.18 Reading Rot13 Messages 37.19 `movemail' program 37.20 Retrieving Mail from Remote Mailboxes 37.21 Retrieving Mail from Local Mailboxes in Various Formats 38 Dired, the Directory Editor 38.1 Entering Dired 38.2 Navigation in the Dired Buffer 38.3 Deleting Files with Dired 38.4 Flagging Many Files at Once 38.5 Visiting Files in Dired 38.6 Dired Marks vs. Flags 38.7 Operating on Files 38.8 Shell Commands in Dired 38.9 Transforming File Names in Dired 38.10 File Comparison with Dired 38.11 Subdirectories in Dired 38.12 Subdirectory Switches in Dired 38.13 Moving Over Subdirectories 38.14 Hiding Subdirectories 38.15 Updating the Dired Buffer 38.16 Dired and `find' 38.17 Editing the Dired Buffer 38.18 Viewing Image Thumbnails in Dired 38.19 Other Dired Features 39 The Calendar and the Diary 39.1 Movement in the Calendar 39.1.1 Motion by Standard Lengths of Time 39.1.2 Beginning or End of Week, Month or Year 39.1.3 Specified Dates 39.2 Scrolling in the Calendar 39.3 Counting Days 39.4 Miscellaneous Calendar Commands 39.5 Writing Calendar Files 39.6 Holidays 39.7 Times of Sunrise and Sunset 39.8 Phases of the Moon 39.9 Conversion To and From Other Calendars 39.9.1 Supported Calendar Systems 39.9.2 Converting To Other Calendars 39.9.3 Converting From Other Calendars 39.9.4 Converting from the Mayan Calendar 39.10 The Diary 39.10.1 Displaying the Diary 39.10.2 The Diary File 39.10.3 Date Formats 39.10.4 Commands to Add to the Diary 39.10.5 Special Diary Entries 39.11 Appointments 39.12 Importing and Exporting Diary Entries 39.13 Daylight Saving Time 39.14 Summing Time Intervals 39.15 Customizing the Calendar and Diary 39.15.1 Customizing the Calendar 39.15.2 Customizing the Holidays 39.15.3 Date Display Format 39.15.4 Time Display Format 39.15.5 Customizing the Diary 39.15.6 Hebrew- and Islamic-Date Diary Entries 39.15.7 Fancy Diary Display 39.15.8 Sexp Entries and the Fancy Diary Display 40 Gnus 40.1 Gnus Buffers 40.2 When Gnus Starts Up 40.3 Summary of Gnus Commands 41 Running Shell Commands from Emacs 41.1 Single Shell Commands 41.2 Interactive Inferior Shell 41.3 Shell Mode 41.4 Shell Prompts 41.5 Shell Command History 41.5.1 Shell History Ring 41.5.2 Shell History Copying 41.5.3 Shell History References 41.6 Directory Tracking 41.7 Shell Mode Options 41.8 Emacs Terminal Emulator 41.9 Term Mode 41.10 Page-At-A-Time Output 41.11 Remote Host Shell 42 Using Emacs as a Server 42.1 Invoking `emacsclient' 43 Printing Hard Copies 44 PostScript Hardcopy 45 Variables for PostScript Hardcopy 46 Printing Package 47 Sorting Text 48 Narrowing 49 Two-Column Editing 50 Editing Binary Files 51 Saving Emacs Sessions 52 Recursive Editing Levels 53 Emulation 54 Hyperlinking and Navigation Features 54.1 Following URLs 54.2 Activating URLs 54.3 Finding Files and URLs at Point 55 Dissociated Press 56 Other Amusements 57 Customization 57.1 Minor Modes 57.2 Easy Customization Interface 57.2.1 Customization Groups 57.2.2 Browsing and Searching for Options and Faces 57.2.3 Changing a Variable 57.2.4 Saving Customizations 57.2.5 Customizing Faces 57.2.6 Customizing Specific Items 57.2.7 Customization Themes 57.3 Variables 57.3.1 Examining and Setting Variables 57.3.2 Hooks 57.3.3 Local Variables 57.3.4 Local Variables in Files 57.3.4.1 Specifying File Variables 57.3.4.2 Safety of File Variables 57.4 Customizing Key Bindings 57.4.1 Keymaps 57.4.2 Prefix Keymaps 57.4.3 Local Keymaps 57.4.4 Minibuffer Keymaps 57.4.5 Changing Key Bindings Interactively 57.4.6 Rebinding Keys in Your Init File 57.4.7 Rebinding Function Keys 57.4.8 Named ASCII Control Characters 57.4.9 Rebinding Mouse Buttons 57.4.10 Disabling Commands 57.5 The Syntax Table 57.6 The Init File, `~/.emacs' 57.6.1 Init File Syntax 57.6.2 Init File Examples 57.6.3 Terminal-specific Initialization 57.6.4 How Emacs Finds Your Init File 57.6.5 Non-ASCII Characters in Init Files 58 Quitting and Aborting 59 Dealing with Emacs Trouble 59.1 If Fails to Delete 59.2 Recursive Editing Levels 59.3 Garbage on the Screen 59.4 Garbage in the Text 59.5 Running out of Memory 59.6 Recovery After a Crash 59.7 Emergency Escape 59.8 Help for Total Frustration 60 Reporting Bugs 60.1 When Is There a Bug 60.2 Understanding Bug Reporting 60.3 Checklist for Bug Reports 60.4 Sending Patches for GNU Emacs 61 Contributing to Emacs Development 62 How To Get Help with GNU Emacs Appendix A GNU GENERAL PUBLIC LICENSE Preamble How to Apply These Terms to Your New Programs Appendix B GNU Free Documentation License ADDENDUM: How to use this License for your documents Appendix C Command Line Arguments for Emacs Invocation C.1 Action Arguments C.2 Initial Options C.3 Command Argument Example C.4 Resuming Emacs with Arguments C.5 Environment Variables C.5.1 General Variables C.5.2 Miscellaneous Variables C.5.3 The MS-Windows System Registry C.6 Specifying the Display Name C.7 Font Specification Options C.8 Window Color Options C.9 Options for Window Size and Position C.10 Internal and External Borders C.11 Frame Titles C.12 Icons C.13 Other Display Options Appendix D X Options and Resources D.1 X Resources D.2 Table of X Resources for Emacs D.3 X Resources for Faces D.4 Lucid Menu X Resources D.5 LessTif Menu X Resources D.6 GTK resources D.6.1 GTK widget names D.6.2 GTK Widget Names in Emacs D.6.3 GTK styles Appendix E Emacs 21 Antinews Appendix F Emacs and Mac OS F.1 Keyboard and Mouse Input on Mac F.2 International Character Set Support on Mac F.3 Environment Variables and Command Line Arguments. F.4 Volumes and Directories on Mac F.5 Specifying Fonts on Mac F.6 Mac-Specific Lisp Functions Appendix G Emacs and Microsoft Windows/MS-DOS G.1 Text Files and Binary Files G.2 File Names on MS-Windows G.3 Emulation of `ls' on MS-Windows G.4 HOME Directory on MS-Windows G.5 Keyboard Usage on MS-Windows G.6 Mouse Usage on MS-Windows G.7 Subprocesses on Windows 9X/ME and Windows NT/2K/XP G.8 Printing and MS-Windows G.9 Miscellaneous Windows-specific features G.10 Emacs and MS-DOS G.10.1 Keyboard Usage on MS-DOS G.10.2 Mouse Usage on MS-DOS G.10.3 Display on MS-DOS G.10.4 File Names on MS-DOS G.10.5 Printing and MS-DOS G.10.6 International Support on MS-DOS G.10.7 Subprocesses on MS-DOS The GNU Manifesto What's GNU? Gnu's Not Unix! Why I Must Write GNU Why GNU Will Be Compatible with Unix How GNU Will Be Available Why Many Other Programmers Want to Help How You Can Contribute Why All Computer Users Will Benefit Some Easily Rebutted Objections to GNU's Goals Glossary Acknowledgments Key (Character) Index Command-Line Options Index Command and Function Index Variable Index Concept Index The Emacs Editor **************** Emacs is the extensible, customizable, self-documenting real-time display editor. This Info file describes how to edit with Emacs and some of how to customize it; it corresponds to GNU Emacs version 22.1. To learn more about the Info documentation system, type `h', and Emacs will take you to a programmed instruction sequence for the Info commands. For information on extending Emacs, see *Note Emacs Lisp: (elisp)Top. Distribution ************ GNU Emacs is "free software"; this means that everyone is free to use it and free to redistribute it on 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 manual(1). *Note Copying::. 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. You can also order copies of GNU Emacs from the Free Software Foundation. This is a convenient and reliable way to get a copy; it is also a good way to help fund our work. We also sell hardcopy versions of this manual and `An Introduction to Programming in Emacs Lisp', by Robert J. Chassell. You can find an order form on our web site at `http://www.gnu.org/order/order.html'. For further information, write to Free Software Foundation 51 Franklin Street, Fifth Floor Boston, MA 02110-1301 USA The income from distribution fees goes to support the foundation's purpose: the development of new free software, and improvements to our existing programs including GNU Emacs. 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. If company policy is unsympathetic to the idea of donating to charity, you might instead suggest ordering a CD-ROM from the Foundation occasionally, or subscribing to periodic updates. ---------- Footnotes ---------- (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. *Note GNU Free Documentation License::. Introduction ************ You are reading about GNU Emacs, the GNU incarnation of the advanced, self-documenting, customizable, extensible editor Emacs. (The `G' in `GNU' is not silent.) We call Emacs advanced because it provides much more than simple insertion and deletion. It can control subprocesses, indent programs automatically, show two or more files at once, and edit formatted text. Emacs editing commands operate in terms of characters, words, lines, sentences, paragraphs, and pages, as well as expressions and comments in various programming languages. "Self-documenting" means that at any time you can type a special character, `Control-h', to find out what your options are. You can also use it to find out what any command does, or to find all the commands that pertain to a topic. *Note Help::. "Customizable" means that you can alter Emacs commands' behavior in simple ways. For example, 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 (*note Comments::). Another sort of customization is rearrangement of the command set. For example, you can rebind the basic cursor motion commands (up, down, left and right) to any keys on the keyboard that you find comfortable. *Note Customization::. "Extensible" means that you can go beyond simple customization and write entirely new commands--programs in the Lisp language to be run by Emacs's own Lisp interpreter. Emacs is an "on-line extensible" system, which means that it is divided into many functions that call each other, any of which can be redefined in the middle of an editing session. Almost any part of Emacs can be replaced without making a separate copy of all of Emacs. Most of the editing commands of 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. *Note Emacs Lisp Intro: (eintr)Top, if you want to learn Emacs Lisp programming. When running on a graphical display, Emacs provides its own menus and convenient handling of mouse buttons. In addition, Emacs provides many of the benefits of a graphical display even on a text-only terminal. For instance, it can highlight parts of a file, display and edit several files at once, move text between files, and edit files while running shell commands. 1 The Organization of the Screen ******************************** On a text-only terminal, the Emacs display occupies the whole screen. On a graphical display, such as on GNU/Linux using the X Window System, Emacs creates its own windows to use. We use the term "frame" to mean the entire text-only screen or an entire system-level window used by Emacs. Emacs uses both kinds of frames, in the same way, to display your editing. Emacs normally starts out with just one frame, but you can create additional frames if you wish. *Note Frames::. When you start Emacs, the main central area of the frame, all except for the top and bottom and sides, displays the text you are editing. This area is called "the window". At the top there is normally a "menu bar" where you can access a series of menus; then there may be a "tool bar", a row of icons that perform editing commands if you click on them. Below this, the window begins, often with a "scroll bar" on one side. Below the window comes the last line of the frame, a special "echo area" or "minibuffer window", where prompts appear and you enter information when Emacs asks for it. See following sections for more information about these special lines. You can subdivide the window horizontally or vertically to make multiple text windows, each of which can independently display some file or text (*note Windows::). In this manual, the word "window" refers to the initial large window if not subdivided, or any one of the multiple windows you have subdivided it into. At any time, one window is the "selected window". On graphical displays, the selected window normally shows a more prominent cursor (usually solid and blinking) while other windows show a weaker cursor (such as a hollow box). Text terminals have just one cursor, so it always appears in the selected window. Most Emacs commands implicitly apply to the text in the selected window; the text in unselected windows is mostly visible for reference. However, mouse commands generally operate on whatever window you click them in, whether selected or not. If you use multiple frames on a graphical display, then giving the input focus to a particular frame selects a window in that frame. Each window's last line is a "mode line", which describes what is going on in that window. It appears in different color and/or a "3D" box if the terminal supports them; its contents normally begin with `--:-- *scratch*' when Emacs starts. The mode line displays status information such as what buffer is being displayed above it in the window, what major and minor modes are in use, and whether the buffer contains unsaved changes. 1.1 Point ========= Within Emacs, the active cursor shows the location at which editing commands will take effect. This location is called "point". Many Emacs commands move point through the text, so that you can edit at different places in it. You can also place point by clicking mouse button 1 (normally the left button). While the cursor appears to be _on_ a character, you should think of point as _between_ two characters; it points _before_ the character that appears under the cursor. For example, if your text looks like `frob' with the cursor over the `b', then point is between the `o' and the `b'. If you insert the character `!' at that position, the result is `fro!b', with point between the `!' and the `b'. Thus, the cursor remains over the `b', as before. Sometimes people speak of "the cursor" when they mean "point," or speak of commands that move point as "cursor motion" commands. If you are editing several files in Emacs, each in its own buffer, each buffer has its own point location. A buffer that is not currently displayed remembers its point location in case you display it again later. When Emacs displays multiple windows, each window has its own point location. If the same buffer appears in more than one window, each window has its own point position in that buffer, and (when possible) its own cursor. A text-only terminal has just one cursor, in the selected window. The other windows do not show a cursor, even though they do have their own position of point. When Emacs updates the screen on a text-only terminal, it has to put the cursor temporarily at the place the output goes. This doesn't mean point is there, though. Once display updating finishes, Emacs puts the cursor where point is. On graphical displays, Emacs shows a cursor in each window; the selected window's cursor is solid and blinking, and the other cursors are just hollow. Thus, the most prominent cursor always shows you the selected window, on all kinds of terminals. *Note Cursor Display::, for customizable variables that control display of the cursor or cursors. The term "point" comes from the character `.', which was the command in TECO (the language in which the original Emacs was written) for accessing the value now called "point." 1.2 The Echo Area ================= The line at the bottom of the frame (below the mode line) is the "echo area". It is used to display small amounts of text for various purposes. "Echoing" means displaying the characters that you type. At the command line, the operating system normally echoes all your input. Emacs handles echoing differently. Single-character commands do not echo in Emacs, and multi-character commands echo only if you pause while typing them. As soon as you pause for more than a second in the middle of a command, Emacs echoes all the characters of the command so far. This is to "prompt" you for the rest of the command. Once echoing has started, the rest of the command echoes immediately as you type it. This behavior is designed to give confident users fast response, while giving hesitant users maximum feedback. You can change this behavior by setting a variable (*note Display Custom::). If a command cannot do its job, it may display an "error message" in the echo area. Error messages are accompanied by beeping or by flashing the screen. The error also discards any input you have typed ahead. Some commands display informative messages in the echo area. These messages look much like error messages, but they are not announced with a beep and do not throw away input. Sometimes the message tells you what the command has done, when this is not obvious from looking at the text being edited. Sometimes the sole purpose of a command is to show you a message giving you specific information--for example, `C-x =' (hold down and type `x', then let go of and type `=') displays a message describing the character position of point in the text and its current column in the window. Commands that take a long time often display messages ending in `...' while they are working, and add `done' at the end when they are finished. They may also indicate progress with percentages. Echo-area informative messages are saved in an editor buffer named `*Messages*'. (We have not explained buffers yet; see *Note Buffers::, for more information about them.) If you miss a message that appears briefly on the screen, you can switch to the `*Messages*' buffer to see it again. (Successive progress messages are often collapsed into one in that buffer.) The size of `*Messages*' is limited to a certain number of lines. The variable `message-log-max' specifies how many lines. Once the buffer has that many lines, adding lines at the end deletes lines from the beginning, to keep the size constant. *Note Variables::, for how to set variables such as `message-log-max'. The echo area is also used to display the "minibuffer", a window where you can input arguments to commands, such as the name of a file to be edited. When the minibuffer is in use, the echo area begins with a prompt string that usually ends with a colon; also, the cursor appears in that line because it is the selected window. You can always get out of the minibuffer by typing `C-g'. *Note Minibuffer::. 1.3 The Mode Line ================= Each text window's last line is a "mode line", which describes what is going on in that window. The mode line starts and ends with dashes. When there is only one text window, the mode line appears right above the echo area; it is the next-to-last line in the frame. On a text-only terminal, the mode line is in inverse video if the terminal supports that; on a graphics display, the mode line has a 3D box appearance to help it stand out. The mode line of the selected window is highlighted if possible; see *Note Optional Mode Line::, for more information. Normally, the mode line looks like this: -CS:CH-FR BUF POS LINE (MAJOR MINOR)------ This gives information about the window and the buffer it displays: the buffer's name, what major and minor modes are in use, whether the buffer's text has been changed, and how far down the buffer you are currently looking. CH contains two stars `**' if the text in the buffer has been edited (the buffer is "modified"), or `--' if the buffer has not been edited. For a read-only buffer, it is `%*' if the buffer is modified, and `%%' otherwise. FR gives the selected frame name (*note Frames::). It appears only on text-only terminals. The initial frame's name is `F1'. BUF is the name of the window's "buffer". Usually this is the same as the name of a file you are editing. *Note Buffers::. The buffer displayed in the selected window (the window with the cursor) is the "current buffer", where editing happens. When a command's effect applies to "the buffer," we mean it does those things to the current buffer. POS tells you whether there is additional text above the top of the window, or below the bottom. If your buffer is small and it is all visible in the window, POS is `All'. Otherwise, it is `Top' if you are looking at the beginning of the buffer, `Bot' if you are looking at the end of the buffer, or `NN%', where NN is the percentage of the buffer above the top of the window. With Size Indication mode, you can display the size of the buffer as well. *Note Optional Mode Line::. LINE is `L' followed by the current line number of point. This is present when Line Number mode is enabled (it normally is). You can display the current column number too, by turning on Column Number mode. It is not enabled by default because it is somewhat slower. *Note Optional Mode Line::. MAJOR is the name of the "major mode" in effect in the buffer. A buffer can only be in one major mode at a time. The major modes available include Fundamental mode (the least specialized), Text mode, Lisp mode, C mode, Texinfo mode, and many others. *Note Major Modes::, for details of how the modes differ and how to select them. Some major modes display additional information after the major mode name. For example, Rmail buffers display the current message number and the total number of messages. Compilation buffers and Shell buffers display the status of the subprocess. MINOR is a list of some of the "minor modes" that are turned on at the moment in the window's chosen buffer. For example, `Fill' means that Auto Fill mode is on. `Abbrev' means that Word Abbrev mode is on. `Ovwrt' means that Overwrite mode is on. *Note Minor Modes::, for more information. `Narrow' means that the buffer being displayed has editing restricted to only a portion of its text. (This is not really a minor mode, but is like one.) *Note Narrowing::. `Def' means that a keyboard macro is being defined. *Note Keyboard Macros::. In addition, if Emacs is inside a recursive editing level, square brackets (`[...]') appear around the parentheses that surround the modes. If Emacs is in one recursive editing level within another, double square brackets appear, and so on. Since recursive editing levels affect Emacs globally, not just one buffer, the square brackets appear in every window's mode line or not in any of them. *Note Recursive Edit::. CS states the coding system used for the file you are editing. A dash indicates the default state of affairs: no code conversion, except for end-of-line translation if the file contents call for that. `=' means no conversion whatsoever. Nontrivial code conversions are represented by various letters--for example, `1' refers to ISO Latin-1. *Note Coding Systems::, for more information. On a text-only terminal, CS includes two additional characters which describe the coding system for keyboard input and the coding system for terminal output. They come right before the coding system used for the file you are editing. If you are using an input method, a string of the form `I>' is added to the beginning of CS; I identifies the input method. (Some input methods show `+' or `@' instead of `>'.) *Note Input Methods::. When multibyte characters are not enabled, CS does not appear at all. *Note Enabling Multibyte::. The colon after CS changes to another string in some cases. Emacs uses newline characters to separate lines in the buffer. Some files use different conventions for separating lines: either carriage-return linefeed (the MS-DOS convention) or just carriage-return (the Macintosh convention). If the buffer's file uses carriage-return linefeed, the colon changes to either a backslash (`\') or `(DOS)', depending on the operating system. If the file uses just carriage-return, the colon indicator changes to either a forward slash (`/') or `(Mac)'. On some systems, Emacs displays `(Unix)' instead of the colon for files that use newline as the line separator. *Note Optional Mode Line::, to add other handy information to the mode line, such as the size of the buffer, the current column number of point, and whether new mail for you has arrived. The mode line is mouse-sensitive; when you move the mouse across various parts of it, Emacs displays help text to say what a click in that place will do. *Note Mode Line Mouse::. 1.4 The Menu Bar ================ Each Emacs frame normally has a "menu bar" at the top which you can use to perform common operations. There's no need to list them here, as you can more easily see them yourself. On a graphical display, you can use the mouse to choose a command from the menu bar. A right-arrow at the end of the menu item means it leads to a subsidiary menu; `...' at the end means that the command invoked will read arguments (further input from you) before it actually does anything. You can also invoke the first menu bar item by pressing (to run the command `menu-bar-open'). You can then navigate the menus with the arrow keys. You select an item by pressing and cancel menu navigation with . To view the full command name and documentation for a menu item, type `C-h k', and then select the menu bar with the mouse in the usual way (*note Key Help::). On text-only terminals with no mouse, you can use the menu bar by typing `M-`' or (these run the command `tmm-menubar'). This lets you select a menu item with the keyboard. A provisional choice appears in the echo area. You can use the up and down arrow keys to move through the menu to different items, and then you can type to select the item. Each menu item also has an assigned letter or digit which designates that item; it is usually the initial of some word in the item's name. This letter or digit is separated from the item name by `=>'. You can type the item's letter or digit to select the item. Some of the commands in the menu bar have ordinary key bindings as well; one such binding is shown in parentheses after the item itself. 2 Kinds of User Input ********************* GNU Emacs is designed for use with keyboard commands because that is the most efficient way to edit. You can do editing with the mouse, as in other editors, and you can give commands with the menu bar and tool bar, and scroll with the scroll bar. But if you keep on editing that way, you won't get the benefits of Emacs. Therefore, this manual documents primarily how to edit with the keyboard. You can force yourself to practice using the keyboard by using the shell command `emacs -nw' to start Emacs, so that the mouse won't work. Emacs uses an extension of the ASCII character set for keyboard input; it also accepts non-character input events including function keys and mouse button actions. ASCII consists of 128 character codes. Some of these codes are assigned graphic symbols such as `a' and `='; the rest are control characters, such as `Control-a' (usually written `C-a' for short). `C-a' gets its name from the fact that you type it by holding down the key while pressing `a'. Some ASCII control characters have special names, and most terminals have special keys you can type them with: for example, , , and . The space character is usually known as , even though strictly speaking it is a graphic character that is blank. Emacs extends the ASCII character set with thousands more printing characters (*note International::), additional control characters, and a few more modifiers that can be combined with any character. On ASCII terminals, there are only 32 possible control characters. These are the control variants of letters and `@[]\^_'. In addition, the shift key is meaningless with control characters: `C-a' and `C-A' are the same character, and Emacs cannot distinguish them. The Emacs character set has room for control variants of all printing characters, and distinguishes `C-A' from `C-a'. Graphical terminals make it possible to enter all these characters. For example, `C--' (that's Control-Minus) and `C-5' are meaningful Emacs commands on a graphical terminal. Another Emacs character-set extension is additional modifier bits. Only one modifier bit is commonly used; it is called Meta. Every character has a Meta variant; examples include `Meta-a' (normally written `M-a', for short), `M-A' (different from `M-a', but they are normally equivalent in Emacs), `M-', and `M-C-a'. That last means `a' with both the and modifiers. We usually write it as `C-M-a' rather than `M-C-a', for reasons of tradition. Some terminals have a key, and allow you to type Meta characters by holding this key down. Thus, you can type `Meta-a' by holding down and pressing `a'. The key works much like the key. In fact, this key is more often labeled or , instead of ; on a Sun keyboard, it may have a diamond on it. If there is no key, you can still type Meta characters using two-character sequences starting with . Thus, you can enter `M-a' by typing ` a'. You can enter `C-M-a' by typing ` C-a'. Unlike , which modifies other characters, is a separate character. You don't hold down while typing the next character; instead, you press it and release it, then you enter the next character. is allowed on terminals with keys, too, in case you have formed a habit of using it. Emacs defines several other modifier keys that can be applied to any input character. These are called , and . We write `s-', `H-' and `A-' to say that a character uses these modifiers. Thus, `s-H-C-x' is short for `Super-Hyper-Control-x'. Not all graphical terminals actually provide keys for these modifier flags--in fact, many terminals have a key labeled which is really a key. The standard key bindings of Emacs do not include any characters with these modifiers. But you can assign them meanings of your own by customizing Emacs. If your keyboard lacks one of these modifier keys, you can enter it using `C-x @': `C-x @ h' adds the "hyper" flag to the next character, `C-x @ s' adds the "super" flag, and `C-x @ a' adds the "alt" flag. For instance, `C-x @ h C-a' is a way to enter `Hyper-Control-a'. (Unfortunately there is no way to add two modifiers by using `C-x @' twice for the same character, because the first one goes to work on the `C-x'.) Keyboard input includes keyboard keys that are not characters at all, such as function keys and arrow keys. Mouse buttons are also not characters. However, you can modify these events with the modifier keys , , , and , just like keyboard characters. Input characters and non-character inputs are collectively called "input events". *Note Input Events: (elisp)Input Events, for the full Lisp-level details. If you are not doing Lisp programming, but simply want to redefine the meaning of some characters or non-character events, see *Note Customization::. ASCII terminals cannot really send anything to the computer except ASCII characters. These terminals use a sequence of characters to represent each function key. But that is invisible to the Emacs user, because the keyboard input routines catch these special sequences and convert them to function key events before any other part of Emacs gets to see them. On graphical displays, the window manager is likely to block the character `Meta-' before Emacs can see it. It may also block `Meta-', `C-M-d' and `C-M-l'. If you have these problems, we recommend that you customize your window manager to turn off those commands, or put them on key combinations that Emacs does not use. 3 Keys ****** A "key sequence" ("key", for short) is a sequence of input events that is meaningful as a unit--a "single command." Some Emacs command sequences are invoked by just one character or one event; for example, just `C-f' moves forward one character in the buffer. But Emacs also has commands that take two or more events to invoke. If a sequence of events is enough to invoke a command, it is a "complete key". Examples of complete keys include `C-a', `X', , (a function key), (an arrow key), `C-x C-f', and `C-x 4 C-f'. If it isn't long enough to be complete, we call it a "prefix key". The above examples show that `C-x' and `C-x 4' are prefix keys. Every key sequence is either a complete key or a prefix key. Most single characters constitute complete keys in the standard Emacs command bindings. A few of them are prefix keys. A prefix key combines with the following input event to make a longer key sequence, which may itself be complete or a prefix. For example, `C-x' is a prefix key, so `C-x' and the next input event combine to make a two-event key sequence. Most of these key sequences are complete keys, including `C-x C-f' and `C-x b'. A few, such as `C-x 4' and `C-x r', are themselves prefix keys that lead to three-event key sequences. There's no limit to the length of a key sequence, but in practice people rarely use sequences longer than four events. You can't add input events onto a complete key. For example, the two-event sequence `C-f C-k' is not a key, because the `C-f' is a complete key in itself. It's impossible to give `C-f C-k' an independent meaning as a command. `C-f C-k' is two key sequences, not one. All told, the prefix keys in Emacs are `C-c', `C-h', `C-x', `C-x ', `C-x @', `C-x a', `C-x n', `C-x r', `C-x v', `C-x 4', `C-x 5', `C-x 6', , `M-g', and `M-o'. ( and are aliases for `C-h' and `C-x 6'.) This list is not cast in stone; it describes the standard key bindings. If you customize Emacs, you can make new prefix keys, or eliminate some of the standard ones (not recommended for most users). *Note Key Bindings::. If you make or eliminate prefix keys, that changes the set of possible key sequences. For example, if you redefine `C-f' as a prefix, `C-f C-k' automatically becomes a key (complete, unless you define that too as a prefix). Conversely, if you remove the prefix definition of `C-x 4', then `C-x 4 f' and `C-x 4 ANYTHING' are no longer keys. Typing the help character (`C-h' or ) after a prefix key displays a list of the commands starting with that prefix. There are a few prefix keys after which `C-h' does not work--for historical reasons, they define other meanings for `C-h' which are painful to change. works after all prefix keys. 4 Keys and Commands ******************* This manual is full of passages that tell you what particular keys do. But Emacs does not assign meanings to keys directly. Instead, Emacs assigns meanings to named "commands", and then gives keys their meanings by "binding" them to commands. Every command has a name chosen by a programmer. The name is usually made of a few English words separated by dashes; for example, `next-line' or `forward-word'. A command also has a "function definition" which is a Lisp program; this is how the command does its work. In Emacs Lisp, a command is a Lisp function with special options to read arguments and for interactive use. For more information on commands and functions, see *Note What Is a Function: (elisp)What Is a Function. (The definition here is simplified slightly.) The bindings between keys and commands are recorded in tables called "keymaps". *Note Keymaps::. When we say that "`C-n' moves down vertically one line" we are glossing over a subtle distinction that is irrelevant in ordinary use, but vital for Emacs customization. The command `next-line' does a vertical move downward. `C-n' has this effect _because_ it is bound to `next-line'. If you rebind `C-n' to the command `forward-word', `C-n' will move forward one word instead. Rebinding keys is an important method of customization. In the rest of this manual, we usually ignore this distinction to keep things simple. We will often speak of keys like `C-n' as commands, even though strictly speaking the key is bound to a command. Usually we state the name of the command which really does the work in parentheses after mentioning the key that runs it. For example, we will say that "The command `C-n' (`next-line') moves point vertically down," meaning that the command `next-line' moves vertically down, and the key `C-n' is normally bound to it. Since we are discussing customization, we should tell you about "variables". Often the description of a command will say, "To change this, set the variable `mumble-foo'." A variable is a name used to store a value. Most of the variables documented in this manual are meant for customization: some command or other part of Emacs examines the variable and behaves differently according to the value that you set. You can ignore the information about variables until you are interested in customizing them. Then read the basic information on variables (*note Variables::) and the information about specific variables will make sense. 5 Character Set for Text ************************ Text in Emacs buffers is a sequence of characters. In the simplest case, these are ASCII characters, each stored in one 8-bit byte. Both ASCII control characters (octal codes 000 through 037, and 0177) and ASCII printing characters (codes 040 through 0176) are allowed. The other modifier flags used in keyboard input, such as Meta, are not allowed in buffers. Non-ASCII printing characters can also appear in buffers, when multibyte characters are enabled. They have character codes starting at 256, octal 0400, and each one is represented as a sequence of two or more bytes. *Note International::. Single-byte characters with codes 128 through 255 can also appear in multibyte buffers. However, non-ASCII control characters cannot appear in a buffer. Some ASCII control characters serve special purposes in text, and have special names. For example, the newline character (octal code 012) is used in the buffer to end a line, and the tab character (octal code 011) is used for indenting to the next tab stop column (normally every 8 columns). *Note Text Display::. If you disable multibyte characters, then you can use only one alphabet of non-ASCII characters, which all fit in one byte. They use octal codes 0200 through 0377. *Note Unibyte Mode::. 6 Entering and Exiting Emacs **************************** The usual way to invoke Emacs is with the shell command `emacs'. Emacs clears the screen, then displays an initial help message and copyright notice. Some operating systems discard your type-ahead when Emacs starts up; they give Emacs no way to prevent this. On those systems, wait for Emacs to clear the screen before you start typing. From a shell window under the X Window System, run Emacs in the background with `emacs&'. This way, Emacs won't tie up the shell window, so you can use it to run other shell commands while Emacs is running. You can type Emacs commands as soon as you direct your keyboard input to an Emacs frame. When Emacs starts up, it creates a buffer named `*scratch*'. That's the buffer you start out in. The `*scratch*' buffer uses Lisp Interaction mode; you can use it to type Lisp expressions and evaluate them. You can also ignore that capability and just write notes there. You can specify a different major mode for this buffer by setting the variable `initial-major-mode' in your init file. *Note Init File::. It is possible to specify files to be visited, Lisp files to be loaded, and functions to be called through Emacs command-line arguments. *Note Emacs Invocation::. The feature exists mainly for compatibility with other editors, and for scripts. Many editors are designed to edit one file. When done with that file, you exit the editor. The next time you want to edit a file, you must start the editor again. Working this way, it is convenient to use a command-line argument to say which file to edit. However, killing Emacs after editing one each and starting it afresh for the next file is both unnecessary and harmful, since it denies you the full power of Emacs. Emacs can visit more than one file in a single editing session, and that is the right way to use it. Exiting the Emacs session loses valuable accumulated context, such as the kill ring, registers, undo history, and mark ring. These features are useful for operating on multiple files, or even continuing to edit one file. If you kill Emacs after each file, you don't take advantage of them. The recommended way to use GNU Emacs is to start it only once, just after you log in, and do all your editing in the same Emacs session. Each time you edit a file, you visit it with the existing Emacs, which eventually has many files in it ready for editing. Usually you do not kill Emacs until you are about to log out. *Note Files::, for more information on visiting more than one file. To edit a file from another program while Emacs is running, you can use the `emacsclient' helper program to open a file in the already running Emacs. *Note Emacs Server::. 7 Exiting Emacs *************** There are two commands for exiting Emacs, and three kinds of exiting: "iconifying" Emacs, "suspending" Emacs, and "killing" Emacs. "Iconifying" means replacing the Emacs frame with a small box or "icon" on the screen. This is the usual way to exit Emacs when you're using a graphical display--if you bother to "exit" at all. (Just switching to another application is usually sufficient.) "Suspending" means stopping Emacs temporarily and returning control to its parent process (usually a shell), allowing you to resume editing later in the same Emacs job. This is the usual way to exit Emacs when running it on a text terminal. "Killing" Emacs means destroying the Emacs job. You can run Emacs again later, but you will get a fresh Emacs; there is no way to resume the same editing session after it has been killed. `C-z' Suspend Emacs (`suspend-emacs') or iconify a frame (`iconify-or-deiconify-frame'). `C-x C-c' Kill Emacs (`save-buffers-kill-emacs'). On graphical displays, `C-z' runs the command `iconify-or-deiconify-frame', which temporarily iconifies (or "minimizes") the selected Emacs frame (*note Frames::). You can then use the window manager to select some other application. (You could select another application without iconifying Emacs first, but getting the Emacs frame out of the way can make it more convenient to find the other application.) On a text terminal, `C-z' runs the command `suspend-emacs'. Suspending Emacs takes you back to the shell from which you invoked Emacs. You can resume Emacs with the shell command `%emacs' in most common shells. On systems that don't support suspending programs, `C-z' starts an inferior shell that communicates directly with the terminal, and Emacs waits until you exit the subshell. (The way to do that is probably with `C-d' or `exit', but it depends on which shell you use.) On these systems, you can only get back to the shell from which Emacs was run (to log out, for example) when you kill Emacs. Suspending can fail if you run Emacs under a shell that doesn't support suspendion of its subjobs, even if the system itself does support it. In such a case, you can set the variable `cannot-suspend' to a non-`nil' value to force `C-z' to start an inferior shell. To exit and kill Emacs, type `C-x C-c' (`save-buffers-kill-emacs'). A two-character key is used to make it harder to type by accident. This command first offers to save any modified file-visiting buffers. If you do not save them all, it asks for confirmation with `yes' before killing Emacs, since any changes not saved now will be lost forever. Also, if any subprocesses are still running, `C-x C-c' asks for confirmation about them, since killing Emacs will also kill the subprocesses. If the value of the variable `confirm-kill-emacs' is non-`nil', `C-x C-c' assumes that its value is a predicate function, and calls that function. If the result is non-`nil', the session is killed, otherwise Emacs continues to run. One convenient function to use as the value of `confirm-kill-emacs' is the function `yes-or-no-p'. The default value of `confirm-kill-emacs' is `nil'. You can't resume an Emacs session after killing it. Emacs can, however, record certain session information when you kill it, such as which files you visited, so the next time you start Emacs it will try to visit the same files. *Note Saving Emacs Sessions::. The operating system usually listens for certain special characters whose meaning is to kill or suspend the program you are running. This operating system feature is turned off while you are in Emacs. The meanings of `C-z' and `C-x C-c' as keys in Emacs were inspired by the use of `C-z' and `C-c' on several operating systems as the characters for stopping or killing a program, but that is their only relationship with the operating system. You can customize these keys to run any commands of your choice (*note Keymaps::). 8 Basic Editing Commands ************************ Here we explain the basics of how to enter text, make corrections, and save the text in a file. If this material is new to you, we suggest you first run the Emacs learn-by-doing tutorial, by typing `Control-h t' inside Emacs. (`help-with-tutorial'). To clear and redisplay the screen, type `C-l' (`recenter'). 8.1 Inserting Text ================== Typing printing characters inserts them into the text you are editing. It inserts them into the buffer at the cursor; more precisely, it inserts them at "point", but the cursor normally shows where point is. *Note Point::. Insertion moves the cursor forward, and the following text moves forward with the cursor. If the text in the buffer is `FOOBAR', with the cursor before the `B', and you type `XX', you get `FOOXXBAR', with the cursor still before the `B'. To "delete" text you have just inserted, use the large key labeled , or which is a short distance above the or key. Regardless of the label on that key, Emacs thinks of it as , and that's what we call it in this manual. is the key you normally use outside Emacs to erase the last character that you typed. The key deletes the character _before_ the cursor. As a consequence, the cursor and all the characters after it move backwards. If you type a printing character and then type , they cancel out. On most computers, Emacs sets up automatically. In some cases, especially with text-only terminals, Emacs may guess wrong. If the key that ought to erase the last character doesn't do it in Emacs, see *Note DEL Does Not Delete::. Most PC keyboards have both a key a little ways above or , and a key elsewhere. On these keyboards, Emacs tries to set up as . The key deletes "forwards" like `C-d' (see below), which means it deletes the character underneath the cursor (after point). To end a line and start typing a new one, type . (This key may be labeled or , but in Emacs we call it .) This inserts a newline character in the buffer. If point is at the end of the line, this creates a new blank line after it. If point is in the middle of a line, the effect is to split that line. Typing when the cursor is at the beginning of a line deletes the preceding newline character, thus joining the line with the one before it. Emacs can split lines automatically when they become too long, if you turn on a special minor mode called "Auto Fill" mode. *Note Filling::, for Auto Fill mode and other methods of "filling" text. If you prefer printing characters to replace (overwrite) existing text, rather than shove it to the right, you should enable Overwrite mode, a minor mode. *Note Minor Modes::. Only printing characters and insert themselves in Emacs. Other characters act as editing commands and do not insert themselves. These include control characters, and characters with codes above 200 octal. If you need to insert one of these characters in the buffer, you must "quote" it by typing the character `Control-q' (`quoted-insert') first. (This character's name is normally written `C-q' for short.) There are two ways to use `C-q': * `C-q' followed by any non-graphic character (even `C-g') inserts that character. * `C-q' followed by a sequence of octal digits inserts the character with the specified octal character code. You can use any number of octal digits; any non-digit terminates the sequence. If the terminating character is , it serves only to terminate the sequence. Any other non-digit terminates the sequence and then acts as normal input--thus, `C-q 1 0 1 B' inserts `AB'. The use of octal sequences is disabled in ordinary non-binary Overwrite mode, to give you a convenient way to insert a digit instead of overwriting with it. When multibyte characters are enabled, if you specify a code in the range 0200 through 0377 octal, `C-q' assumes that you intend to use some ISO 8859-N character set, and converts the specified code to the corresponding Emacs character code. *Note Enabling Multibyte::. You select _which_ of the ISO 8859 character sets to use through your choice of language environment (*note Language Environments::). To use decimal or hexadecimal instead of octal, set the variable `read-quoted-char-radix' to 10 or 16. If the radix is greater than 10, some letters starting with `a' serve as part of a character code, just like digits. A numeric argument tells `C-q' how many copies of the quoted character to insert (*note Arguments::). Customization information: in most modes runs the command `delete-backward-char'; runs the command `newline', and self-inserting printing characters run the command `self-insert', which inserts whatever character you typed. Some major modes rebind to other commands. 8.2 Changing the Location of Point ================================== To do more than insert characters, you have to know how to move point (*note Point::). The simplest way to do this is with arrow keys, or by clicking the left mouse button where you want to move to. There are also control and meta characters for cursor motion. Some are equivalent to the arrow keys (it is faster to use these control keys than move your hand over to the arrow keys). Others do more sophisticated things. `C-a' Move to the beginning of the line (`move-beginning-of-line'). `C-e' Move to the end of the line (`move-end-of-line'). `C-f' Move forward one character (`forward-char'). The right-arrow key does the same thing. `C-b' Move backward one character (`backward-char'). The left-arrow key has the same effect. `M-f' Move forward one word (`forward-word'). `M-b' Move backward one word (`backward-word'). `C-n' Move down one line vertically (`next-line'). This command attempts to keep the horizontal position unchanged, so if you start in the middle of one line, you move to the middle of the next. The down-arrow key does the same thing. `C-p' Move up one line, vertically (`previous-line'). The up-arrow key has the same effect. This command preserves position within the line, like `C-n'. `M-r' Move point to left margin, vertically centered in the window (`move-to-window-line'). Text does not move on the screen. A numeric argument says which screen line to place point on, counting downward from the top of the window (zero means the top line). A negative argument counts lines up from the bottom (-1 means the bottom line). `M-<' Move to the top of the buffer (`beginning-of-buffer'). With numeric argument N, move to N/10 of the way from the top. *Note Arguments::, for more information on numeric arguments. `M->' Move to the end of the buffer (`end-of-buffer'). `C-v' `' `' Scroll the display one screen forward, and move point if necessary to put it on the screen (`scroll-up'). This doesn't always move point, but it is commonly used to do so. If your keyboard has a or key, it does the same thing. Scrolling commands are described further in *Note Scrolling::. `M-v' `' `' Scroll one screen backward, and move point if necessary to put it on the screen (`scroll-down'). This doesn't always move point, but it is commonly used to do so. If your keyboard has a or key, it does the same thing. `M-x goto-char' Read a number N and move point to buffer position N. Position 1 is the beginning of the buffer. `M-g M-g' `M-g g' `M-x goto-line' Read a number N and move point to the beginning of line number N. Line 1 is the beginning of the buffer. If point is on or just after a number in the buffer, and you type with the minibuffer empty, that number is used for N. `C-x C-n' Use the current column of point as the "semipermanent goal column" for `C-n' and `C-p' (`set-goal-column'). When a semipermanent goal column is in effect, those commands always try to move to this column, or as close as possible to it, after moving vertically. The goal column remains in effect until canceled. `C-u C-x C-n' Cancel the goal column. Henceforth, `C-n' and `C-p' try to preserve the horizontal position, as usual. If you set the variable `track-eol' to a non-`nil' value, then `C-n' and `C-p', when starting at the end of the line, move to the end of another line. Normally, `track-eol' is `nil'. *Note Variables::, for how to set variables such as `track-eol'. `C-n' normally stops at the end of the buffer when you use it on the last line of the buffer. However, if you set the variable `next-line-add-newlines' to a non-`nil' value, `C-n' on the last line of a buffer creates an additional line at the end and moves down into it. 8.3 Erasing Text ================ `' Delete the character before point (`delete-backward-char'). `C-d' Delete the character after point (`delete-char'). `' `' One of these keys, whichever is the large key above the or key, deletes the character before point--it is . If is , and your keyboard also has , then deletes forwards, like `C-d'. `C-k' Kill to the end of the line (`kill-line'). `M-d' Kill forward to the end of the next word (`kill-word'). `M-' Kill back to the beginning of the previous word (`backward-kill-word'). You already know about the key which deletes the character before point (that is, before the cursor). Another key, `Control-d' (`C-d' for short), deletes the character after point (that is, the character that the cursor is on). This shifts the rest of the text on the line to the left. If you type `C-d' at the end of a line, it joins that line with the following line. To erase a larger amount of text, use the `C-k' key, which erases (kills) a line at a time. If you type `C-k' at the beginning or middle of a line, it kills all the text up to the end of the line. If you type `C-k' at the end of a line, it joins that line with the following line. *Note Killing::, for more flexible ways of killing text. 8.4 Undoing Changes =================== Emacs records a list of changes made in the buffer text, so you can you can undo recent changes, as far as the records go. Usually each editing command makes a separate entry in the undo records, but sometimes an entry covers just part of a command, and very simple commands may be grouped. `C-x u' Undo one entry of the undo records--usually, one command worth (`undo'). `C-_' `C-/' The same. The command `C-x u' (or `C-_' or `C-/') is how you undo. Normally this command undoes the last change, and moves point back to where it was before the change. If you repeat `C-x u' (or its aliases), each repetition undoes another, earlier change, back to the limit of the undo information available. If all recorded changes have already been undone, the undo command displays an error message and does nothing. The undo command applies only to changes in the buffer; you can't use it to undo mere cursor motion. However, some cursor motion commands set the mark, so if you use these commands from time to time, you can move back to the neighborhoods you have moved through by popping the mark ring (*note Mark Ring::). 8.5 Files ========= Text that you insert in an Emacs buffer lasts only as long as the Emacs session. To keep any text permanently you must put it in a "file". Files are named units of text which are stored by the operating system for you to retrieve later by name. To use the contents of a file in any way, you must specify the file name. That includes editing the file with Emacs. Suppose there is a file named `test.emacs' in your home directory. To begin editing this file in Emacs, type C-x C-f test.emacs Here the file name is given as an "argument" to the command `C-x C-f' (`find-file'). That command uses the "minibuffer" to read the argument, and you type to terminate the argument (*note Minibuffer::). Emacs obeys this command by "visiting" the file: it creates a buffer, it copies the contents of the file into the buffer, and then displays the buffer for editing. If you alter the text, you can "save" the new text in the file by typing `C-x C-s' (`save-buffer'). This copies the altered buffer contents back into the file `test.emacs', making them permanent. Until you save, the changed text exists only inside Emacs, and the file `test.emacs' is unaltered. To create a file, just visit it with `C-x C-f' as if it already existed. This creates an empty buffer, in which you can insert the text you want to put in the file. Emacs actually creates the file the first time you save this buffer with `C-x C-s'. To learn more about using files in Emacs, see *Note Files::. 8.6 Help ======== If you forget what a key does, you can find out with the Help character, which is `C-h' (or , which is an alias for `C-h'). Type `C-h k' followed by the key of interest; for example, `C-h k C-n' tells you what `C-n' does. `C-h' is a prefix key; `C-h k' is just one of its subcommands (the command `describe-key'). The other subcommands of `C-h' provide different kinds of help. Type `C-h' twice to get a description of all the help facilities. *Note Help::. 8.7 Blank Lines =============== Here are special commands and techniques for inserting and deleting blank lines. `C-o' Insert one or more blank lines after the cursor (`open-line'). `C-x C-o' Delete all but one of many consecutive blank lines (`delete-blank-lines'). To insert a new line of text before an existing line, type the new line of text, followed by . However, it may be easier to see what you are doing if you first make a blank line and then insert the desired text into it. This is easy to do using the key `C-o' (`open-line'), which inserts a newline after point but leaves point in front of the newline. After `C-o', type the text for the new line. `C-o F O O' has the same effect as `F O O ', except for the final location of point. You can make several blank lines by typing `C-o' several times, or by giving it a numeric argument specifying how many blank lines to make. *Note Arguments::, for how. If you have a fill prefix, the `C-o' command inserts the fill prefix on the new line, if typed at the beginning of a line. *Note Fill Prefix::. The easy way to get rid of extra blank lines is with the command `C-x C-o' (`delete-blank-lines'). `C-x C-o' in a run of several blank lines deletes all but one of them. `C-x C-o' on a lone blank line deletes that one. When point is on a nonblank line, `C-x C-o' deletes all following blank lines (if any). 8.8 Continuation Lines ====================== When a text line is too long to fit in one screen line, Emacs displays it on two or more screen lines. This is called "continuation" or "line wrapping". On graphical displays, Emacs indicates line wrapping with small bent arrows in the left and right window fringes. On text-only terminals, Emacs displays a `\' character at the right margin of a screen line if it is not the last in its text line. This `\' character says that the following screen line is not really a new text line. When line wrapping occurs just before a character that is wider than one column, some columns at the end of the previous screen line may be "empty." In this case, Emacs displays additional `\' characters in the "empty" columns before the `\' character that indicates continuation. Continued lines can be difficult to read, since lines can break in the middle of a word. If you prefer, you can make Emacs insert a newline automatically when a line gets too long, by using Auto Fill mode. Or enable Long Lines mode, which ensures that wrapping only occurs between words. *Note Filling::. Emacs can optionally "truncate" long lines--this means displaying just one screen line worth, and the rest of the long line does not appear at all. `$' in the last column or a small straight arrow in the window's right fringe indicates a truncated line. *Note Line Truncation::, for more about line truncation, and other variables that control how text is displayed. 8.9 Cursor Position Information =============================== Here are commands to get information about the size and position of parts of the buffer, and to count lines. `M-x what-page' Display the page number of point, and the line number within that page. `M-x what-line' Display the line number of point in the whole buffer. `M-x line-number-mode' `M-x column-number-mode' Toggle automatic display of the current line number or column number. *Note Optional Mode Line::. `M-=' Display the number of lines in the current region (`count-lines-region'). *Note Mark::, for information about the region. `C-x =' Display the character code of character after point, character position of point, and column of point (`what-cursor-position'). `M-x hl-line-mode' Enable or disable highlighting of the current line. *Note Cursor Display::. `M-x size-indication-mode' Toggle automatic display of the size of the buffer. *Note Optional Mode Line::. `M-x what-line' displays the current line number in the echo area. You can also see the current line number in the mode line; see *Note Mode Line::; but if you narrow the buffer, the line number in the mode line is relative to the accessible portion (*note Narrowing::). By contrast, `what-line' shows both the line number relative to the narrowed region and the line number relative to the whole buffer. `M-x what-page' counts pages from the beginning of the file, and counts lines within the page, showing both numbers in the echo area. *Note Pages::. Use `M-=' (`count-lines-region') to displays the number of lines in the region (*note Mark::). *Note Pages::, for the command `C-x l' which counts the lines in the current page. The command `C-x =' (`what-cursor-position') shows what cursor's column position, and other information about point and the character after it. It displays a line in the echo area that looks like this: Char: c (99, #o143, #x63) point=28062 of 36168 (78%) column=53 The four values after `Char:' describe the character that follows point, first by showing it and then by giving its character code in decimal, octal and hex. For a non-ASCII multibyte character, these are followed by `file' and the character's representation, in hex, in the buffer's coding system, if that coding system encodes the character safely and with a single byte (*note Coding Systems::). If the character's encoding is longer than one byte, Emacs shows `file ...'. However, if the character displayed is in the range 0200 through 0377 octal, it may actually stand for an invalid UTF-8 byte read from a file. In Emacs, that byte is represented as a sequence of 8-bit characters, but all of them together display as the original invalid byte, in octal code. In this case, `C-x =' shows `part of display ...' instead of `file'. `point=' is followed by the position of point expressed as a character count. The start of the buffer is position 1, one character later is position 2, and so on. The next, larger, number is the total number of characters in the buffer. Afterward in parentheses comes the position expressed as a percentage of the total size. `column=' is followed by the horizontal position of point, in columns from the left edge of the window. If the buffer has been narrowed, making some of the text at the beginning and the end temporarily inaccessible, `C-x =' displays additional text describing the currently accessible range. For example, it might display this: Char: C (67, #o103, #x43) point=252 of 889 (28%) <231-599> column=0 where the two extra numbers give the smallest and largest character position that point is allowed to assume. The characters between those two positions are the accessible ones. *Note Narrowing::. If point is at the end of the buffer (or the end of the accessible part), the `C-x =' output does not describe a character after point. The output might look like this: point=36169 of 36168 (EOB) column=0 `C-u C-x =' displays the following additional information about a character. * The character set name, and the codes that identify the character within that character set; ASCII characters are identified as belonging to the `ascii' character set. * The character's syntax and categories. * The character's encodings, both internally in the buffer, and externally if you were to save the file. * What keys to type to input the character in the current input method (if it supports the character). * If you are running Emacs on a graphical display, the font name and glyph code for the character. If you are running Emacs on a text-only terminal, the code(s) sent to the terminal. * The character's text properties (*note Text Properties: (elisp)Text Properties.), and any overlays containing it (*note Overlays: (elisp)Overlays.). Here's an example showing the Latin-1 character A with grave accent, in a buffer whose coding system is `iso-latin-1', whose terminal coding system is `iso-latin-1' (so the terminal actually displays the character as `A`'), and which has font-lock-mode (*note Font Lock::) enabled: character: A` (2240, #o4300, #x8c0, U+00C0) charset: latin-iso8859-1 (Right-Hand Part of Latin Alphabet 1... code point: #x40 syntax: w which means: word category: l:Latin to input: type "`A" with latin-1-prefix buffer code: #x81 #xC0 file code: #xC0 (encoded by coding system iso-latin-1) display: terminal code #xC0 There are text properties here: fontified t 8.10 Numeric Arguments ====================== In mathematics and computer usage, "argument" means "data provided to a function or operation." You can give any Emacs command a "numeric argument" (also called a "prefix argument"). Some commands interpret the argument as a repetition count. For example, `C-f' with an argument of ten moves forward ten characters instead of one. With these commands, no argument is equivalent to an argument of one. Negative arguments tell most such commands to move or act in the opposite direction. If your terminal keyboard has a key (labeled on PC keyboards), the easiest way to specify a numeric argument is to type digits and/or a minus sign while holding down the key. For example, M-5 C-n moves down five lines. The characters `Meta-1', `Meta-2', and so on, as well as `Meta--', do this because they are keys bound to commands (`digit-argument' and `negative-argument') that are defined to set up an argument for the next command. `Meta--' without digits normally means -1. Digits and `-' modified with Control, or Control and Meta, also specify numeric arguments. You can also specify a numeric argument by typing `C-u' (`universal-argument') followed by the digits. The advantage of `C-u' is that you can type the digits without modifier keys; thus, `C-u' works on all terminals. For a negative argument, type a minus sign after `C-u'. A minus sign without digits normally means -1. `C-u' alone has the special meaning of "four times": it multiplies the argument for the next command by four. `C-u C-u' multiplies it by sixteen. Thus, `C-u C-u C-f' moves forward sixteen characters. This is a good way to move forward "fast," since it moves about 1/5 of a line in the usual size screen. Other useful combinations are `C-u C-n', `C-u C-u C-n' (move down a good fraction of a screen), `C-u C-u C-o' (make "a lot" of blank lines), and `C-u C-k' (kill four lines). Some commands care whether there is an argument, but ignore its value. For example, the command `M-q' (`fill-paragraph') fills text; with an argument, it justifies the text as well. (*Note Filling::, for more information on `M-q'.) Plain `C-u' is a handy way of providing an argument for such commands. Some commands use the value of the argument as a repeat count, but do something peculiar when there is no argument. For example, the command `C-k' (`kill-line') with argument N kills N lines, including their terminating newlines. But `C-k' with no argument is special: it kills the text up to the next newline, or, if point is right at the end of the line, it kills the newline itself. Thus, two `C-k' commands with no arguments can kill a nonblank line, just like `C-k' with an argument of one. (*Note Killing::, for more information on `C-k'.) A few commands treat a plain `C-u' differently from an ordinary argument. A few others may treat an argument of just a minus sign differently from an argument of -1. These unusual cases are described when they come up; they exist to make an individual command more convenient, and they are documented in that command's documentation string. You can use a numeric argument before a self-inserting character to insert multiple copies of it. This is straightforward when the character is not a digit; for example, `C-u 6 4 a' inserts 64 copies of the character `a'. But this does not work for inserting digits; `C-u 6 4 1' specifies an argument of 641. You can separate the argument from the digit to insert with another `C-u'; for example, `C-u 6 4 C-u 1' does insert 64 copies of the character `1'. We use the term "prefix argument" as well as "numeric argument," to emphasize that you type these argument before the command, and to distinguish them from minibuffer arguments that come after the command. 8.11 Repeating a Command ======================== Many simple commands, such as those invoked with a single key or with `M-x COMMAND-NAME ', can be repeated by invoking them with a numeric argument that serves as a repeat count (*note Arguments::). However, if the command you want to repeat prompts for input, or uses a numeric argument in another way, that method won't work. The command `C-x z' (`repeat') provides another way to repeat an Emacs command many times. This command repeats the previous Emacs command, whatever that was. Repeating a command uses the same arguments that were used before; it does not read new arguments each time. To repeat the command more than once, type additional `z''s: each `z' repeats the command one more time. Repetition ends when you type a character other than `z', or press a mouse button. For example, suppose you type `C-u 2 0 C-d' to delete 20 characters. You can repeat that command (including its argument) three additional times, to delete a total of 80 characters, by typing `C-x z z z'. The first `C-x z' repeats the command once, and each subsequent `z' repeats it once again. 9 The Minibuffer **************** The "minibuffer" is where Emacs commands read complicated arguments (anything more a single number). We call it the "minibuffer" because it's a special-purpose buffer with a small amount of screen space. Minibuffer arguments can be file names, buffer names, Lisp function names, Emacs command names, Lisp expressions, and many other things--whatever the command wants to read. You can use the usual Emacs editing commands in the minibuffer to edit the argument text. When the minibuffer is in use, it appears in the echo area, with a cursor. The minibuffer display starts with a "prompt" in a distinct color; it says what kind of input is expected and how it will be used. Often the prompt is derived from the name of the command that is reading the argument. The prompt normally ends with a colon. Sometimes a "default argument" appears in the prompt, inside parentheses before the colon. The default will be used as the argument value if you just type . For example, commands that read buffer names show a buffer name as the default. You can type to operate on that default buffer. The simplest way to enter a minibuffer argument is to type the text, then to exit the minibuffer. You can cancel the minibuffer, and the command that wants the argument, by typing `C-g'. Since the minibuffer appears in the echo area, it can conflict with other uses of the echo area. Here is how Emacs handles such conflicts: * An error occurs while the minibuffer is active. The error message hides the minibuffer for a few seconds, or until you type something. Then the minibuffer comes back. * A command such as `C-x =' needs to display a message in the echo area. The message hides the minibuffer for a few seconds, or until you type something. Then the minibuffer comes back. * Keystrokes don't echo while the minibuffer is in use. 9.1 Minibuffers for File Names ============================== When you use the minibuffer to enter a file name, it starts out with some initial text--the "default directory", ending in a slash. The file you specify will be in this directory unless you alter or replace it. For example, if the minibuffer starts out with these contents: Find File: /u2/emacs/src/ (where `Find File: ' is the prompt), and you type `buffer.c' as input, that specifies the file `/u2/emacs/src/buffer.c'. You can specify the parent directory by adding `..'; thus, if you type `../lisp/simple.el', you will get `/u2/emacs/lisp/simple.el'. Alternatively, you can use `M-' to kill the directory names you don't want (*note Words::). You can kill the entire default with `C-a C-k', but there's no need to do that. It's easier to ignore the default, and enter an absolute file name starting with a slash or a tilde after the default directory. For example, to specify `/etc/termcap', just type that name: Find File: /u2/emacs/src//etc/termcap GNU Emacs interprets a double slash (which is not normally useful in file names) as, "ignore everything before the second slash in the pair." In the example above. `/u2/emacs/src/' is ignored, so you get `/etc/termcap'. The ignored part of the file name is dimmed if the terminal allows it; to disable this dimming, turn off File Name Shadow mode (a minor mode) with the command `M-x file-name-shadow-mode'. If the variable `insert-default-directory' is `nil', the default directory is never inserted in the minibuffer--so the minibuffer starts out empty. Nonetheless, relative file name arguments are still interpreted based on the same default directory. 9.2 Editing in the Minibuffer ============================= The minibuffer is an Emacs buffer (albeit a peculiar one), and the usual Emacs commands are available for editing the argument text. Since in the minibuffer is defined to exit the minibuffer, you can't use it to insert a newline in the minibuffer. To do that, type `C-o' or `C-q C-j'. (The newline character is really the ASCII character control-J.) The minibuffer has its own window, which normally has space in the frame at all times, but it only acts like an Emacs window when the minibuffer is active. When active, this window is much like any other Emacs window; for instance, you can switch to another window (with `C-x o'), edit text there, then return to the minibuffer window to finish the argument. You can even kill text in another window, return to the minibuffer window, and then yank the text into the argument. *Note Windows::. There are some restrictions on the minibuffer window, however: you cannot kill it, or split it, or switch buffers in it--the minibuffer and its window are permanently attached. The minibuffer window expands vertically as necessary to hold the text that you put in the minibuffer. If `resize-mini-windows' is `t' (the default), the window always resizes as needed by its contents. If its value is the symbol `grow-only', the window grows automatically as needed, but shrinks (back to the normal size) only when the minibuffer becomes inactive. If its value is `nil', you have to adjust the height yourself. The variable `max-mini-window-height' controls the maximum height for resizing the minibuffer window: a floating-point number specifies a fraction of the frame's height; an integer specifies the maximum number of lines; `nil' means do not resize the minibuffer window automatically. The default value is 0.25. The `C-M-v' command in the minibuffer scrolls the help text from commands that display help text of any sort in another window. `M-' and `M-' also operate on that help text. This is especially useful with long lists of possible completions. *Note Other Window::. Emacs normally disallows most commands that use the minibuffer while the minibuffer is active. (Entering the minibuffer from the minibuffer can be confusing.) To allow such commands in the minibuffer, set the variable `enable-recursive-minibuffers' to `t'. 9.3 Completion ============== Some arguments allow "completion" to enter their value. This means that after you type part of the argument, Emacs can fill in the rest, or some of it, based on what you have typed so far. When completion is available, certain keys--, , and --are rebound to complete the text in the minibuffer before point into a longer string chosen from a set of "completion alternatives" provided by the command that requested the argument. ( does not do completion in reading file names, because it is common to use spaces in file names on some systems.) `?' displays a list of the possible completions at any time. For example, `M-x' uses the minibuffer to read the name of a command, so it provides a list of all Emacs command names for completion candidates. The completion keys match the minibuffer text against these candidates, find any additional name characters implied by the text already present in the minibuffer, and add those characters. This makes it possible to type `M-x ins b ' instead of `M-x insert-buffer ', for example. Case is significant in completion when it is significant in the argument you are entering (buffer names, file names, command names, for instance). Thus, `fo' does not complete to `Foo'. Completion ignores case distinctions for certain arguments in which case does not matter. Completion acts only on the text before point. If there is text in the minibuffer after point--i.e., if you move point backward after typing some text into the minibuffer--it remains unchanged. 9.3.1 Completion Example ------------------------ A concrete example may help here. If you type `M-x au ', the looks for alternatives (in this case, command names) that start with `au'. There are several, including `auto-fill-mode' and `auto-save-mode', but they all begin with `auto-', so the `au' in the minibuffer completes to `auto-'. If you type again immediately, it cannot determine the next character; it could be any of `cfilrs'. So it does not add any characters; instead, displays a list of all possible completions in another window. Now type `f '. This sees `auto-f'. The only command name starting with that is `auto-fill-mode', so completion fills in the rest of that. You have been able to enter `auto-fill-mode' by typing just `au f '. 9.3.2 Completion Commands ------------------------- Here is a list of the completion commands defined in the minibuffer when completion is allowed. `' Complete the text before point in the minibuffer as much as possible (`minibuffer-complete'). `' Complete up to one word from the minibuffer text before point (`minibuffer-complete-word'). for completion is not available when entering a file name, since file names often include spaces. `' Submit the text in the minibuffer as the argument, possibly completing first as described in the next node (`minibuffer-complete-and-exit'). *Note Strict Completion::. `?' Display a list of possible completions of the text before point (`minibuffer-completion-help'). completes like , but only up to the next hyphen or space. If you have `auto-f' in the minibuffer and type , it finds that the completion is `auto-fill-mode', but it only inserts `ill-', giving `auto-fill-'. Another at this point completes all the way to `auto-fill-mode'. The command that implements this behavior is called `minibuffer-complete-word'. When you display a list of possible completions, you can choose one from it: `Mouse-1' `Mouse-2' Clicking mouse button 1 or 2 on a completion possibility chooses that completion (`mouse-choose-completion'). You must click in the list of completions, not in the minibuffer. `' `M-v' Typing or , or `M-v', while in the minibuffer, selects the window showing the completion list buffer (`switch-to-completions'). This paves the way for using the commands below. (Selecting that window in other ways has the same effect.) `' Typing _in the completion list buffer_ chooses the completion that point is in or next to (`choose-completion'). To use this command, you must first switch to the completion list window. `' Typing the right-arrow key _in the completion list buffer_ moves point to the following completion possibility (`next-completion'). `' Typing the left-arrow key _in the completion list buffer_ moves point to the previous completion possibility (`previous-completion'). 9.3.3 Strict Completion ----------------------- There are three different ways that can do completion, depending on how the argument will be used. * "Strict" completion accepts only known completion candidates. For example, when `C-x k' reads the name of a buffer to kill, only the name of an existing buffer makes sense. In strict completion, refuses to exit if the text in the minibuffer does not complete to an exact match. * "Cautious" completion is similar to strict completion, except that exits only if the text is an already exact match. Otherwise, does not exit, but it does complete the text. If that completes to an exact match, a second will exit. Cautious completion is used for reading file names for files that must already exist, for example. * "Permissive" completion allows any input; the completion candidates are just suggestions. For example, when `C-x C-f' reads the name of a file to visit, any file name is allowed, including nonexistent file (in case you want to create a file). In permissive completion, does not complete, it just submits the argument as you have entered it. The completion commands display a list of all possible completions whenever they can't determine even one more character by completion. Also, typing `?' explicitly requests such a list. You can scroll the list with `C-M-v' (*note Other Window::). 9.3.4 Completion Options ------------------------ When completing file names, certain file names are usually ignored. The variable `completion-ignored-extensions' contains a list of strings; a file name ending in any of those strings is ignored as a completion candidate. The standard value of this variable has several elements including `".o"', `".elc"', `".dvi"' and `"~"'. The effect is that, for example, `foo' can complete to `foo.c' even though `foo.o' exists as well. However, if _all_ the possible completions end in "ignored" strings, then they are not ignored. Displaying a list of possible completions disregards `completion-ignored-extensions'; it shows them all. If an element of `completion-ignored-extensions' ends in a slash (`/'), it's a subdirectory name; then that directory and its contents are ignored. Elements of `completion-ignored-extensions' which do not end in a slash are ordinary file names, and do not apply to names of directories. If `completion-auto-help' is set to `nil', the completion commands never display a list of possibilities; you must type `?' to display the list. Partial Completion mode implements a more powerful kind of completion that can complete multiple words in parallel. For example, it can complete the command name abbreviation `p-b' into `print-buffer' if no other command starts with two words whose initials are `p' and `b'. To enable this mode, use `M-x partial-completion-mode', or customize the variable `partial-completion-mode'. This mode binds special partial completion commands to , , , and `?' in the minibuffer. The usual completion commands are available on `M-' (or `C-M-i'), `M-', `M-' and `M-?'. Partial completion of directories in file names uses `*' to indicate the places for completion; thus, `/u*/b*/f*' might complete to `/usr/bin/foo'. For remote files, partial completion enables completion of methods, user names and host names. *Note Remote Files::. Partial Completion mode also extends `find-file' so that `' looks for the file named INCLUDE in the directories in the path `PC-include-file-path'. If you set `PC-disable-includes' to non-`nil', this feature is disabled. Icomplete mode presents a constantly-updated display that tells you what completions are available for the text you've entered so far. The command to enable or disable this minor mode is `M-x icomplete-mode'. 9.4 Minibuffer History ====================== Every argument that you enter with the minibuffer is saved on a "minibuffer history list" so you can easily use it again later. Special commands fetch the text of an earlier argument into the minibuffer, replacing the old minibuffer contents. You can think of them as moving through the history of previous arguments. `' `M-p' Move to the previous item in the minibuffer history, an earlier argument (`previous-history-element'). `' `M-n' Move to the next item in the minibuffer history (`next-history-element'). `M-r REGEXP ' Move to an earlier item in the minibuffer history that matches REGEXP (`previous-matching-history-element'). `M-s REGEXP ' Move to a later item in the minibuffer history that matches REGEXP (`next-matching-history-element'). To move through the minibuffer history list one item at a time, use `M-p' or up-arrow (`previous-history-element') to fetch the next earlier minibuffer input, and use `M-n' or down-arrow (`next-history-element') to fetch the next later input. These commands don't move the cursor, they pull different saved strings into the minibuffer. But you can think of them as "moving" through the history list. The input that you fetch from the history entirely replaces the contents of the minibuffer. To use it again unchanged, just type . You can also edit the text before you reuse it; this does not change the history element that you "moved" to, but your new argument does go at the end of the history list in its own right. For many minibuffer arguments there is a "default" value. You can insert the default value into the minibuffer as text by using `M-n'. You can think of this as moving "into the future" in the history. There are also commands to search forward or backward through the history; they search for history elements that match a regular expression. `M-r' (`previous-matching-history-element') searches older elements in the history, while `M-s' (`next-matching-history-element') searches newer elements. These commands are unusual; they use the minibuffer to read the regular expression even though they are invoked from the minibuffer. As with incremental searching, an upper-case letter in the regular expression makes the search case-sensitive (*note Search Case::). All uses of the minibuffer record your input on a history list, but there are separate history lists for different kinds of arguments. For example, there is a list for file names, used by all the commands that read file names. (As a special feature, this history list records the absolute file name, even if the name you entered was not absolute.) There are several other specific history lists, including one for buffer names, one for arguments of commands like `query-replace', one used by `M-x' for command names, and one used by `compile' for compilation commands. Finally, there is one "miscellaneous" history list that most minibuffer arguments use. The variable `history-length' specifies the maximum length of a minibuffer history list; adding a new element deletes the oldest element if the list gets too long. If the value of `history-length' is `t', though, there is no maximum length. The variable `history-delete-duplicates' specifies whether to delete duplicates in history. If it is `t', adding a new element deletes from the list all other elements that are equal to it. 9.5 Repeating Minibuffer Commands ================================= Every command that uses the minibuffer once is recorded on a special history list, the "command history", together with the values of its arguments, so that you can repeat the entire command. In particular, every use of `M-x' is recorded there, since `M-x' uses the minibuffer to read the command name. `C-x ' Re-execute a recent minibuffer command from the command history (`repeat-complex-command'). `M-x list-command-history' Display the entire command history, showing all the commands `C-x ' can repeat, most recent first. `C-x ' is used to re-execute a recent command that used the minibuffer. With no argument, it repeats the last such command. A numeric argument specifies which command to repeat; 1 means the last one, 2 the previous, and so on. `C-x ' works by turning the previous command into a Lisp expression and then entering a minibuffer initialized with the text for that expression. Even if you don't understand Lisp syntax, it will probably be obvious which command is displayed for repetition. If you type just , that repeats the command unchanged. You can also change the command by editing the Lisp expression before you execute it. The repeated command is added to the front of the command history unless it is identical to the most recently item. Once inside the minibuffer for `C-x ', you can use the minibuffer history commands (`M-p', `M-n', `M-r', `M-s'; *note Minibuffer History::) to move through the history list of saved entire commands. After finding the desired previous command, you can edit its expression as usual and then repeat it by typing . Incremental search does not, strictly speaking, use the minibuffer. Therefore, although it behaves like a complex command, it normally does not appear in the history list for `C-x '. You can make incremental search commands appear in the history by setting `isearch-resume-in-command-history' to a non-`nil' value. *Note Incremental Search::. The list of previous minibuffer-using commands is stored as a Lisp list in the variable `command-history'. Each element is a Lisp expression which describes one command and its arguments. Lisp programs can re-execute a command by calling `eval' with the `command-history' element. 10 Running Commands by Name *************************** Every Emacs command has a name that you can use to run it. For convenience, many commands also have key bindings. You can run those commands by typing the keys, or run them by name. Most Emacs commands have no key bindings, so the only way to run them is by name. (*Note Key Bindings::, for how to set up key bindings.) By convention, a command name consists of one or more words, separated by hyphens; for example, `auto-fill-mode' or `manual-entry'. Command names mostly use complete English words to make them easier to remember. To run a command by name, start with `M-x', type the command name, then terminate it with . `M-x' uses the minibuffer to read the command name. The string `M-x' appears at the beginning of the minibuffer as a "prompt" to remind you to enter a command name to be run. exits the minibuffer and runs the command. *Note Minibuffer::, for more information on the minibuffer. You can use completion to enter the command name. For example, to invoke the command `forward-char', you can type M-x forward-char or M-x forw c Note that `forward-char' is the same command that you invoke with the key `C-f'. The existence of a key binding does not stop you from running the command by name. To cancel the `M-x' and not run a command, type `C-g' instead of entering the command name. This takes you back to command level. To pass a numeric argument to the command you are invoking with `M-x', specify the numeric argument before `M-x'. The argument value appears in the prompt while the command name is being read, and finally `M-x' passes the argument to that command. When the command you run with `M-x' has a key binding, Emacs mentions this in the echo area after running the command. For example, if you type `M-x forward-word', the message says that you can run the same command by typing `M-f'. You can turn off these messages by setting the variable `suggest-key-bindings' to `nil'. In this manual, when we speak of running a command by name, we often omit the that terminates the name. Thus we might say `M-x auto-fill-mode' rather than `M-x auto-fill-mode '. We mention the only for emphasis, such as when the command is followed by arguments. `M-x' works by running the command `execute-extended-command', which is responsible for reading the name of another command and invoking it. 11 Help ******* Emacs provides extensive help features, all accessible through the "help character", `C-h'. This is a prefix key that is used for commands that display documentation; the next character you type should be a "help options", to ask for a particular kind of help. You can cancel the `C-h' command with `C-g'. The function key is equivalent to `C-h'. `C-h' itself is one of the help options; `C-h C-h' displays a list of help options, with a brief description of each one (`help-for-help'). You can scroll the list with and , then type the help option you want. To cancel, type `C-g'. `C-h' or means "help" in various other contexts as well. For instance, you can type them after a prefix key to display list of the keys that can follow the prefix key. (A few prefix keys don't support `C-h' in this way, because they define other meanings for it, but they all support for help.) Most help buffers use a special major mode, Help mode, which lets you scroll conveniently with and . You can also follow hyperlinks to URLs, and to other facilities including Info nodes and customization buffers. *Note Help Mode::. If you are looking for a certain feature, but don't know what it is called or where to look, we recommend three methods. First, try an apropos command, then try searching the manual index, then look in the FAQ and the package keywords. `C-h a TOPICS ' This searches for commands whose names match the argument TOPICS. The argument can be a keyword, a list of keywords, or a regular expression (*note Regexps::). This command displays all the matches in a new buffer. *Note Apropos::. `C-h i d m emacs i TOPIC ' This searches for TOPIC in the indices of the on-line Emacs manual, and displays the first match found. Press `,' to see subsequent matches. You can use a regular expression as TOPIC. `C-h i d m emacs s TOPIC ' Similar, but searches the _text_ of the manual rather than the indices. `C-h C-f' This displays the Emacs FAQ. You can use the Info commands to browse it. `C-h p' This displays the available Emacs packages based on keywords. *Note Library Keywords::. 11.1 Help Summary ================= Here is a summary of the Emacs interactive help commands. (The character that follows `C-h' is the "help option.") *Note Help Files::, for other help commands that display fixed files of information. `C-h a TOPICS ' Display a list of commands whose names match TOPICS (`apropos-command'; *note Apropos::). `C-h b' Display all active key bindings; minor mode bindings first, then those of the major mode, then global bindings (`describe-bindings'). `C-h c KEY' Given a key sequence KEY, show the name of the command that it runs (`describe-key-briefly'). Here `c' stands for "character." For more extensive information on KEY, use `C-h k'. `C-h d TOPICS ' Display the commands and variables whose documentation matches TOPICS (`apropos-documentation'). `C-h e' Display the `*Messages*' buffer (`view-echo-area-messages'). `C-h f FUNCTION ' Display documentation on the Lisp function named FUNCTION (`describe-function'). Since commands are Lisp functions, this works for commands too. `C-h h' Display the `HELLO' file, which shows examples of various character sets. `C-h i' Run Info, the GNU documentation browser (`info'). The complete Emacs manual is available on-line in Info. `C-h k KEY' Display the name and documentation of the command that KEY runs (`describe-key'). `C-h l' Display a description of the last 100 characters you typed (`view-lossage'). `C-h m' Display documentation of the current major mode (`describe-mode'). `C-h p' Find packages by topic keyword (`finder-by-keyword'). `C-h s' Display the current contents of the syntax table, with an explanation of what they mean (`describe-syntax'). *Note Syntax::. `C-h t' Enter the Emacs interactive tutorial (`help-with-tutorial'). `C-h v VAR ' Display the documentation of the Lisp variable VAR (`describe-variable'). `C-h w COMMAND ' Show which keys run the command named COMMAND (`where-is'). `C-h C CODING ' Describe the coding system CODING (`describe-coding-system'). `C-h C ' Describe the coding systems currently in use. `C-h I METHOD ' Describe the input method METHOD (`describe-input-method'). `C-h L LANGUAGE-ENV ' Display information on the character sets, coding systems, and input methods used in language environment LANGUAGE-ENV (`describe-language-environment'). `C-h F FUNCTION ' Enter Info and goes to the node that documents the Emacs function FUNCTION (`Info-goto-emacs-command-node'). `C-h K KEY' Enter Info and goes to the node that documents the key sequence KEY (`Info-goto-emacs-key-command-node'). `C-h S SYMBOL ' Display the Info documentation on symbol SYMBOL according to the programming language you are editing (`info-lookup-symbol'). `C-h .' Display the help message for a special text area, if point is in one (`display-local-help'). (These include, for example, links in `*Help*' buffers.) 11.2 Documentation for a Key ============================ The help commands to get information about a key sequence are `C-h c' and `C-h k'. `C-h c KEY' displays in the echo area the name of the command that KEY is bound to. For example, `C-h c C-f' displays `forward-char'. Since command names are chosen to describe what the commands do, this gives you a very brief description of what KEY does. `C-h k KEY' is similar but gives more information: it displays the documentation string of the command as well as its name. It displays this information in a window, since it may not fit in the echo area. To find the documentation of a key sequence KEY, type `C-h K KEY'. This displays the appropriate manual section which contains the documentation of KEY. `C-h c', `C-h k' and `C-h K' work for any sort of key sequences, including function keys, menus, and mouse events. For instance, after `C-h k' you can select a menu item from the menu bar, to view the documentation string of the command it runs. `C-h w COMMAND ' lists the keys that are bound to COMMAND. It displays the list in the echo area. If it says the command is not on any key, that means you must use `M-x' to run it. `C-h w' runs the command `where-is'. 11.3 Help by Command or Variable Name ===================================== `C-h f FUNCTION ' (`describe-function') displays the documentation of Lisp function FUNCTION, in a window. Since commands are Lisp functions, you can use this method to view the documentation of any command whose name you know. For example, C-h f auto-fill-mode displays the documentation of `auto-fill-mode'. This is the only way to get the documentation of a command that is not bound to any key (one which you would normally run using `M-x'). `C-h f' is also useful for Lisp functions that you use in a Lisp program. For example, if you have just written the expression `(make-vector len)' and want to check that you are using `make-vector' properly, type `C-h f make-vector '. Because `C-h f' allows all function names, not just command names, you may find that some of your favorite completion abbreviations that work in `M-x' don't work in `C-h f'. An abbreviation that is unique among command names may not be unique among all function names. If you type `C-h f ', it describes the function called by the innermost Lisp expression in the buffer around point, _provided_ that function name is a valid, defined Lisp function. (That name appears as the default while you enter the argument.) For example, if point is located following the text `(make-vector (car x)', the innermost list containing point is the one that starts with `(make-vector', so `C-h f ' will describe the function `make-vector'. `C-h f' is also useful just to verify that you spelled a function name correctly. If the minibuffer prompt for `C-h f' shows the function name from the buffer as the default, it means that name is defined as a Lisp function. Type `C-g' to cancel the `C-h f' command if you don't really want to view the documentation. `C-h v' (`describe-variable') is like `C-h f' but describes Lisp variables instead of Lisp functions. Its default is the Lisp symbol around or before point, if that is the name of a defined Lisp variable. *Note Variables::. Help buffers that describe Emacs variables and functions normally have hyperlinks to the corresponding source definition, if you have the source files installed. (*Note Hyperlinking::.) If you know Lisp (or C), this provides the ultimate documentation. If you don't know Lisp, you should learn it. (The Introduction to Emacs Lisp Programming, available from the FSF through fsf.org, is a good way to get started.) If Emacs feels you are just _using_ it, treating it as an object program, its feelings may be hurt. For real intimacy, read the Emacs source code. To find a function's documentation in a manual, use `C-h F' (`Info-goto-emacs-command-node'). This knows about various manuals, not just the Emacs manual, and finds the right one. 11.4 Apropos ============ The "apropos" commands answer questions like, "What are the commands for working with files?" More precisely, you specify an "apropos pattern", which means either a word, a list of words, or a regular expression. Each apropos command displays a list of items that match the pattern, in a separate buffer. `C-h a PATTERN ' Search for commands whose names match PATTERN. `M-x apropos PATTERN ' Search for functions and variables whose names match PATTERN. Both interactive functions (commands) and noninteractive functions can be found by this command. `M-x apropos-variable PATTERN ' Search for user-option variables whose names match PATTERN. `M-x apropos-value PATTERN ' Search for functions whose definitions PATTERN, and variables whose values match PATTERN. `C-h d PATTERN ' Search for functions and variables whose *documentation strings* match PATTERN. The simplest kind of apropos pattern is one word. Anything which contains that word matches the pattern. Thus, to find the commands that work on files, type `C-h a file '. This displays a list of all command names that contain `file', including `copy-file', `find-file', and so on. Each command name comes with a brief description and a list of keys you can currently invoke it with. In our example, it would say that you can invoke `find-file' by typing `C-x C-f'. The `a' in `C-h a' stands for "Apropos"; `C-h a' runs the command `apropos-command'. This command normally checks only commands (interactive functions); if you specify a prefix argument, it checks noninteractive functions as well. For more information about a function definition, variable or symbol property listed in the apropos buffer, you can click on it with `Mouse-1' or `Mouse-2', or move there and type . When you specify more than one word in the apropos pattern, a name must contain at least two of the words in order to match. Thus, if you are looking for commands to kill a chunk of text before point, you could try `C-h a kill back backward behind before '. The real command name `kill-backward' will match that; if there were a command `kill-text-before', it would also match, since it contains two of the specified words. For even greater flexibility, you can specify a regular expression (*note Regexps::). An apropos pattern is interpreted as a regular expression if it contains any of the regular expression special characters, `^$*+?.\['. Following the conventions for naming Emacs commands, here are some words that you'll find useful in apropos patterns. By using them in `C-h a', you will also get a feel for the naming conventions. char, line, word, sentence, paragraph, region, page, sexp, list, defun, rect, buffer, frame, window, face, file, dir, register, mode, beginning, end, forward, backward, next, previous, up, down, search, goto, kill, delete, mark, insert, yank, fill, indent, case, change, set, what, list, find, view, describe, default. Use `M-x apropos' instead of `C-h a' to list all the Lisp symbols that match an apropos pattern, not just the symbols that are commands. This command does not list key bindings by default; specify a numeric argument if you want it to list them. Use `M-x apropos-variable' to list user-customizable variables that match an apropos pattern. If you specify a prefix argument, it lists all matching variables. The `apropos-documentation' command is like `apropos' except that it searches documentation strings instead of symbol names for matches. The `apropos-value' command is like `apropos' except that it searches variables' values for matches for the apropos pattern. With a prefix argument, it also checks symbols' function definitions and property lists. If the variable `apropos-do-all' is non-`nil', the apropos commands always behave as if they had been given a prefix argument. By default, apropos lists the search results in alphabetical order. If the variable `apropos-sort-by-scores' is non-`nil', the apropos commands try to guess the relevance of each result, and display the most relevant ones first. By default, apropos lists the search results for `apropos-documentation' in order of relevance of the match. If the variable `apropos-documentation-sort-by-scores' is `nil', apropos lists the symbols found in alphabetical order. 11.5 Help Mode Commands ======================= Help buffers provide the same commands as View mode (*note Misc File Ops::), plus a few special commands of their own. `' Scroll forward. `' Scroll backward. `' Follow a cross reference at point. `' Move point forward to the next cross reference. `S-' Move point back to the previous cross reference. `Mouse-1' `Mouse-2' Follow a cross reference that you click on. `C-c C-c' Show all documentation about the symbol at point. When a function name (*note Running Commands by Name: M-x.), variable name (*note Variables::), or face name (*note Faces::) appears in the documentation, it normally appears inside paired single-quotes. To view the documentation of that command, variable or face, you can click on the name with `Mouse-1' or `Mouse-2', or move point there and type . Use `C-c C-b' to retrace your steps. You can follow cross references to URLs (web pages) also. This uses the `browse-url' command to view the page in the browser you choose. *Note Browse-URL::. There are convenient commands to move point to cross references in the help text. (`help-next-ref') moves point down to the next cross reference. `S-' moves up to the previous cross reference (`help-previous-ref'). To view all documentation about any symbol name that appears in the text, move point to the symbol name and type `C-c C-c' (`help-follow-symbol'). This shows all available documentation about the symbol as a variable, function and/or face. As above, use `C-c C-b' to retrace your steps. 11.6 Keyword Search for Lisp Libraries ====================================== The `C-h p' command lets you search the standard Emacs Lisp libraries by topic keywords. Here is a partial list of keywords you can use: abbrev abbreviation handling, typing shortcuts, macros. bib code related to the `bib' bibliography processor. c support for the C language and related languages. calendar calendar and time management support. comm communications, networking, remote access to files. convenience convenience features for faster editing. data support for editing files of data. docs support for Emacs documentation. emulations emulations of other editors. extensions Emacs Lisp language extensions. faces support for multiple fonts. files support for editing and manipulating files. frames support for Emacs frames and window systems. games games, jokes and amusements. hardware support for interfacing with exotic hardware. help support for on-line help systems. hypermedia support for links between text or other media types. i18n internationalization and alternate character-set support. internal code for Emacs internals, build process, defaults. languages specialized modes for editing programming languages. lisp Lisp support, including Emacs Lisp. local code local to your site. maint maintenance aids for the Emacs development group. mail modes for electronic-mail handling. matching various sorts of searching and matching. mouse mouse support. multimedia images and sound support. news support for netnews reading and posting. oop support for object-oriented programming. outlines support for hierarchical outlining. processes process, subshell, compilation, and job control support. terminals support for terminal types. tex supporting code for the TeX formatter. tools programming tools. unix front-ends/assistants for, or emulators of, UNIX-like features. wp word processing. 11.7 Help for International Language Support ============================================ You can use the command `C-h L' (`describe-language-environment') to get information about a specific language environment. *Note Language Environments::. This tells you which languages this language environment supports. It also lists the character sets, coding systems, and input methods that work with