GNU Emacs Manual

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 section `Top' in The Emacs Lisp Reference Manual.

Distribution		How to get the latest Emacs distribution.
A. GNU GENERAL PUBLIC LICENSE		The GNU General Public License gives you permission to redistribute GNU Emacs on certain terms; it also explains that there is no warranty.
B. GNU Free Documentation License		The license for this documentation.
Introduction		An introduction to Emacs concepts.
Glossary		The glossary.
E. Emacs 21 Antinews		Information about Emacs version 21.
F. Emacs and Mac OS		Using Emacs in the Mac.
G. Emacs and Microsoft Windows/MS-DOS		Using Emacs on Microsoft Windows and MS-DOS.
The GNU Manifesto		What's GNU? Gnu's Not Unix!
Acknowledgments		Major contributors to GNU Emacs.

Indexes (each index contains a large menu)

Key (Character) Index		An item for each standard Emacs key sequence.
Command-Line Options Index		An item for every command-line option.
Command and Function Index		An item for each command name.
Variable Index		An item for each documented variable.
Concept Index		An item for each concept.

Important General Concepts

1. The Organization of the Screen		How to interpret what you see on the screen.
2. Kinds of User Input		Kinds of input events (characters, buttons, function keys).
3. Keys		Key sequences: what you type to request one editing action.
4. Keys and Commands		Named functions run by key sequences to do editing.
5. Character Set for Text		Character set for text (the contents of buffers and strings).
6. Entering and Exiting Emacs		Starting Emacs from the shell.
7. Exiting Emacs		Stopping or killing Emacs.
C. Command Line Arguments for Emacs Invocation		Hairy startup options.

Fundamental Editing Commands

8. Basic Editing Commands		The most basic editing commands.
9. The Minibuffer		Entering arguments that are prompted for.
10. Running Commands by Name		Invoking commands by their names.
11. Help		Commands for asking Emacs about its commands.

Important Text-Changing Commands

12. The Mark and the Region		The mark: how to delimit a "region" of text.
13. Killing and Moving Text		Killing (cutting) text.
14. Yanking		Recovering killed text. Moving text. (Pasting.)
15. Accumulating Text		Other ways of copying text.
16. Rectangles		Operating on the text inside a rectangle on the screen.
18. Registers		Saving a text string or a location in the buffer.
19. Controlling the Display		Controlling what text is displayed.
20. Searching and Replacement		Finding or replacing occurrences of a string.
21. Commands for Fixing Typos		Commands especially useful for fixing typos.
22. Keyboard Macros		A keyboard macro records a sequence of keystrokes to be replayed with a single command.

Major Structures of Emacs

23. File Handling		All about handling files.
24. Using Multiple Buffers		Multiple buffers; editing several files at once.
25. Multiple Windows		Viewing two pieces of text at once.
26. Frames and Graphical Displays		Running the same Emacs session in multiple X windows.
27. International Character Set Support		Using non-ASCII character sets (the MULE features).

Advanced Features

28. Major Modes		Text mode vs. Lisp mode vs. C mode ...
29. Indentation		Editing the white space at the beginnings of lines.
30. Commands for Human Languages		Commands and modes for editing English.
31. Editing Programs		Commands and modes for editing programs.
32. Compiling and Testing Programs		Compiling, running and debugging programs.
33. Maintaining Large Programs		Features for maintaining large programs.
34. Abbrevs		How to define text abbreviations to reduce the number of characters you must type.
35. Editing Pictures		Editing pictures made up of characters using the quarter-plane screen model.
36. Sending Mail		Sending mail in Emacs.
37. Reading Mail with Rmail		Reading mail in Emacs.
38. Dired, the Directory Editor		You can "edit" a directory to manage files in it.
39. The Calendar and the Diary		The calendar and diary facilities.
40. Gnus		How to read netnews with Emacs.
41. Running Shell Commands from Emacs		Executing shell commands from Emacs.
42. Using Emacs as a Server		Using Emacs as an editing server for mail, etc.
43. Printing Hard Copies		Printing hardcopies of buffers or regions.
47. Sorting Text		Sorting lines, paragraphs or pages within Emacs.
48. Narrowing		Restricting display and editing to a portion of the buffer.
49. Two-Column Editing		Splitting apart columns to edit them in side-by-side windows.
50. Editing Binary Files		Using Hexl mode to edit binary files.
51. Saving Emacs Sessions		Saving Emacs state from one session to the next.
52. Recursive Editing Levels		A command can allow you to do editing

  "within the command".  This is called a
  "recursive editing level".

53. Emulation		Emulating some other editors with Emacs.
54. Hyperlinking and Navigation Features		Following links in buffers.
55. Dissociated Press		Dissociating text for fun.
56. Other Amusements		Various games and hacks.
57. Customization		Modifying the behavior of Emacs.
D. X Options and Resources		X resources for customizing Emacs.

Recovery from Problems

58. Quitting and Aborting		Quitting and aborting.
59. Dealing with Emacs Trouble		What to do if Emacs is hung or malfunctioning.
60. Reporting Bugs		How and when to report a bug.
61. Contributing to Emacs Development		How to contribute improvements to Emacs.
62. How To Get Help with GNU Emacs		How to get help for your own Emacs needs.

 -- The Detailed Node Listing ---
 ---------------------------------

Here are some other nodes which are really inferiors of the ones
already listed, mentioned here so you can get to them in one step:

The Organization of the Screen

1.1 Point		The place in the text where editing commands operate.
1.2 The Echo Area		Short messages appear at the bottom of the screen.
1.3 The Mode Line		Interpreting the mode line.
1.4 The Menu Bar		How to use the menu bar.

Basic Editing Commands

8.1 Inserting Text		Inserting text by simply typing it.
8.2 Changing the Location of Point		How to move the cursor to the place where you want to change something.
8.3 Erasing Text		Deleting and killing text.
8.4 Undoing Changes		Undoing recent changes in the text.
8.5 Files		Visiting, creating, and saving files.
8.6 Help		Asking what a character does.
8.7 Blank Lines		Commands to make or delete blank lines.
8.8 Continuation Lines		Lines too wide for the screen.
8.9 Cursor Position Information		What page, line, row, or column is point on?
8.10 Numeric Arguments		Numeric arguments for repeating a command.
8.11 Repeating a Command		A short-cut for repeating the previous command.

The Minibuffer

9.1 Minibuffers for File Names		Entering file names with the minibuffer.
9.2 Editing in the Minibuffer		How to edit in the minibuffer.
9.3 Completion		An abbreviation facility for minibuffer input.
9.4 Minibuffer History		Reusing recent minibuffer arguments.
9.5 Repeating Minibuffer Commands		Re-executing commands that used the minibuffer.

Completion

9.3.1 Completion Example		Examples of using completion.
9.3.2 Completion Commands		A list of completion commands.
9.3.3 Strict Completion		Different types of completion.
9.3.4 Completion Options		Options for completion.

Help

11.1 Help Summary		Brief list of all Help commands.
11.2 Documentation for a Key		Asking what a key does in Emacs.
11.3 Help by Command or Variable Name		Asking about a command, variable or function name.
11.4 Apropos		Asking what pertains to a given topic.
11.5 Help Mode Commands		Special features of Help mode and Help buffers.
11.6 Keyword Search for Lisp Libraries		Finding Lisp libraries by keywords (topics).
11.7 Help for International Language Support		Help relating to international language support.
11.8 Other Help Commands		Other help commands.
11.9 Help Files		Commands to display pre-written help files.
11.10 Help on Active Text and Tooltips		Help on active text and tooltips (`balloon help')

The Mark and the Region

12.1 Setting the Mark		Commands to set the mark.
12.2 Transient Mark Mode		How to make Emacs highlight the region-- when there is one.
12.3 Using Transient Mark Mode Momentarily		Enabling Transient Mark mode momentarily.
12.4 Operating on the Region		Summary of ways to operate on contents of the region.
12.5 Commands to Mark Textual Objects		Commands to put region around textual units.
12.6 The Mark Ring		Previous mark positions saved so you can go back there.
12.7 The Global Mark Ring		Previous mark positions in various buffers.

Killing and Moving Text

13.1 Deletion		Commands for deleting small amounts of text and blank areas.
13.2 Killing by Lines		How to kill entire lines of text at one time.
13.3 Other Kill Commands		Commands to kill large regions of text and syntactic units such as words and sentences.
17. CUA Bindings		Using C-x, C-c, C-v for copy and paste, with enhanced rectangle support.

Yanking

14.1 The Kill Ring		Where killed text is stored. Basic yanking.
14.2 Appending Kills		Several kills in a row all yank together.
14.3 Yanking Earlier Kills		Yanking something killed some time ago.

Registers

18.1 Saving Positions in Registers		Saving positions in registers.
18.2 Saving Text in Registers		Saving text in registers.
18.3 Saving Rectangles in Registers		Saving rectangles in registers.
18.4 Saving Window Configurations in Registers		Saving window configurations in registers.
18.5 Keeping Numbers in Registers		Numbers in registers.
18.6 Keeping File Names in Registers		File names in registers.
18.7 Bookmarks		Bookmarks are like registers, but persistent.

Controlling the Display

19.1 Scrolling		Moving text up and down in a window.
19.2 Automatic Scrolling		Redisplay scrolls text automatically when needed.
19.3 Horizontal Scrolling		Moving text left and right in a window.
19.4 Follow Mode		Follow mode lets two windows scroll as one.
19.5 Using Multiple Typefaces		How to change the display style using faces.
19.6 Standard Faces		Emacs' predefined faces.
19.7 Font Lock mode		Minor mode for syntactic highlighting using faces.
19.8 Interactive Highlighting		Tell Emacs what text to highlight.
19.9 Window Fringes		Enabling or disabling window fringes.
19.10 Displaying Boundaries		Displaying top and bottom of the buffer.
19.11 Useless Whitespace		Showing possibly-spurious trailing whitespace.
19.12 Selective Display		Hiding lines with lots of indentation.
19.13 Optional Mode Line Features		Optional mode line display features.
19.14 How Text Is Displayed		How text characters are normally displayed.
19.15 Displaying the Cursor		Features for displaying the cursor.
19.16 Truncation of Lines		Truncating lines to fit the screen width instead of continuing them to multiple screen lines.
19.17 Customization of Display		Information on variables for customizing display.

Searching and Replacement

20.1 Incremental Search		Search happens as you type the string.
20.2 Nonincremental Search		Specify entire string and then search.
20.3 Word Search		Search for sequence of words.
20.4 Regular Expression Search		Search for match for a regexp.
20.5 Syntax of Regular Expressions		Syntax of regular expressions.
20.6 Backslash in Regular Expressions		Regular expression constructs starting with `\'.
20.7 Regular Expression Example		A complex regular expression explained.
20.8 Searching and Case		To ignore case while searching, or not.
20.9 Replacement Commands		Search, and replace some or all matches.
20.10 Other Search-and-Loop Commands		Operating on all matches for some regexp.

Incremental Search

20.1.1 Basics of Incremental Search		Basic incremental search commands.
20.1.2 Repeating Incremental Search		Searching for the same string again.
20.1.3 Errors in Incremental Search		When your string is not found.
20.1.4 Special Input for Incremental Search		Special input in incremental search.
20.1.5 Isearch for Non-ASCII Characters		How to search for non-ASCII characters.
20.1.6 Isearch Yanking		Commands that grab text into the search string or else edit the search string.
20.1.7 Lazy Search Highlighting		Isearch highlights the other possible matches.
20.1.8 Scrolling During Incremental Search		Scrolling during an incremental search.
20.1.9 Slow Terminal Incremental Search		Incremental search features for slow terminals.

Replacement Commands

20.9.1 Unconditional Replacement		Replacing all matches for a string.
20.9.2 Regexp Replacement		Replacing all matches for a regexp.
20.9.3 Replace Commands and Case		How replacements preserve case of letters.
20.9.4 Query Replace		How to use querying.

Commands for Fixing Typos

21.1 Undo		Full details of Emacs undo commands.
21.2 Killing Your Mistakes		Commands to kill a batch of recently entered text.
21.3 Transposing Text		Exchanging two characters, words, lines, lists...
21.4 Case Conversion		Correcting case of last word entered.
21.5 Checking and Correcting Spelling		Apply spelling checker to a word or a whole buffer.

Keyboard Macros

22.1 Basic Use		Defining and running keyboard macros.
22.2 The Keyboard Macro Ring		Where previous keyboard macros are saved.
22.3 The Keyboard Macro Counter		Inserting incrementing numbers in macros.
22.4 Executing Macros with Variations		Making keyboard macros do different things each time.
22.5 Naming and Saving Keyboard Macros		Giving keyboard macros names; saving them in files.
22.6 Editing a Keyboard Macro		Editing keyboard macros.
22.7 Stepwise Editing a Keyboard Macro		Interactively executing and editing a keyboard macro.

File Handling

23.1 File Names		How to type and edit file-name arguments.
23.2 Visiting Files		Visiting a file prepares Emacs to edit the file.
23.3 Saving Files		Saving makes your changes permanent.
23.4 Reverting a Buffer		Reverting cancels all the changes not saved.
23.5 Auto Reverting non-file Buffers		Auto Reverting non-file buffers.
23.6 Auto-Saving: Protection Against Disasters		Auto Save periodically protects against loss of data.
23.7 File Name Aliases		Handling multiple names for one file.
23.8 Version Control		Version control systems (RCS, CVS and SCCS).
23.9 File Directories		Creating, deleting, and listing file directories.
23.10 Comparing Files		Finding where two files differ.
23.11 Diff Mode		Editing diff output.
23.12 Miscellaneous File Operations		Other things you can do on files.
23.13 Accessing Compressed Files		Accessing compressed files.
23.14 File Archives		Operating on tar, zip, jar etc. archive files.
23.15 Remote Files		Accessing files on other sites.
23.16 Quoted File Names		Quoting special characters in file names.
23.17 File Name Cache		Completion against a list of files you often use.
23.18 Convenience Features for Finding Files
23.19 Filesets		Handling sets of files.

Saving Files

23.3.1 Commands for Saving Files		Commands for saving files.
23.3.2 Backup Files		How Emacs saves the old version of your file.
23.3.3 Customizing Saving of Files		Customizing the saving of files.
23.3.4 Protection against Simultaneous Editing		How Emacs protects against simultaneous editing of one file by two users.
23.3.5 Shadowing Files		Copying files to "shadows" automatically.
23.3.6 Updating Time Stamps Automatically		Emacs can update time stamps on saved files.

Backup Files

23.3.2.1 Numbered Backups		Whether to make one backup file or many.
23.3.2.2 Single or Numbered Backups		How backup files are named.
23.3.2.3 Automatic Deletion of Backups		Emacs deletes excess numbered backups.
23.3.2.4 Copying vs. Renaming		Backups can be made by copying or renaming.

Auto-Saving: Protection Against Disasters

23.6.1 Auto-Save Files		The file where auto-saved changes are actually made until you save the file.
23.6.2 Controlling Auto-Saving		Controlling when and how often to auto-save.
23.6.3 Recovering Data from Auto-Saves		Recovering text from auto-save files.

Version Control

23.8.1 Introduction to Version Control		How version control works in general.
23.8.2 Version Control and the Mode Line		How the mode line shows version control status.
23.8.3 Basic Editing under Version Control		How to edit a file under version control.
23.8.4 Examining And Comparing Old Versions		Examining and comparing old versions.
23.8.5 The Secondary Commands of VC		The commands used a little less frequently.
23.8.6 Multiple Branches of a File		Multiple lines of development.
23.8.7 Remote Repositories		Efficient access to remote CVS servers.
23.8.8 Snapshots		Sets of file versions treated as a unit.
23.8.9 Miscellaneous Commands and Features of VC		Various other commands and features of VC.
23.8.10 Customizing VC		Variables that change VC's behavior.

Using Multiple Buffers

24.1 Creating and Selecting Buffers		Creating a new buffer or reselecting an old one.
24.2 Listing Existing Buffers		Getting a list of buffers that exist.
24.3 Miscellaneous Buffer Operations		Renaming; changing read-onliness; copying text.
24.4 Killing Buffers		Killing buffers you no longer need.
24.5 Operating on Several Buffers		How to go through the list of all buffers and operate variously on several of them.
24.6 Indirect Buffers		An indirect buffer shares the text of another buffer.
24.7 Convenience Features and Customization of Buffer Handling		Convenience and customization features for buffer handling.

Multiple Windows

25.1 Concepts of Emacs Windows		Introduction to Emacs windows.
25.2 Splitting Windows		New windows are made by splitting existing windows.
25.3 Using Other Windows		Moving to another window or doing something to it.
25.4 Displaying in Another Window		Finding a file or buffer in another window.
25.5 Forcing Display in the Same Window		Forcing certain buffers to appear in the selected window rather than in another window.
25.6 Deleting and Rearranging Windows		Deleting windows and changing their sizes.
25.7 Window Handling Convenience Features and Customization		Convenience functions for window handling.

Frames and Graphical Displays

26.1 Killing and Yanking on Graphical Displays		Mouse commands for cut and paste.
26.2 Following References with the Mouse		Using the mouse to select an item from a list.
26.3 Mouse Clicks for Menus		Mouse clicks that bring up menus.
26.4 Mode Line Mouse Commands		Mouse clicks on the mode line.
26.5 Creating Frames		Creating additional Emacs frames with various contents.
26.6 Frame Commands		Iconifying, deleting, and switching frames.
26.7 Speedbar Frames		How to make and use a speedbar frame.
26.8 Multiple Displays		How one Emacs job can talk to several displays.
26.9 Special Buffer Frames		You can make certain buffers have their own frames.
26.10 Setting Frame Parameters		Changing the colors and other modes of frames.
26.11 Scroll Bars		How to enable and disable scroll bars; how to use them.
26.12 Scrolling With "Wheeled" Mice		Using mouse wheels for scrolling.
26.13 Drag and Drop		Using drag and drop to open files and insert text.
26.14 Menu Bars		Enabling and disabling the menu bar.
26.15 Tool Bars		Enabling and disabling the tool bar.
26.16 Using Dialog Boxes		Controlling use of dialog boxes.
26.17 Tooltips		Showing "tooltips", AKA "balloon help" for active text.
26.18 Mouse Avoidance		Moving the mouse pointer out of the way.
26.19 Non-Window Terminals		Multiple frames on terminals that show only one.
26.20 Using a Mouse in Terminal Emulators		Using the mouse in text-only terminals.

International Character Set Support

27.1 Introduction to International Character Sets		Basic concepts of multibyte characters.
27.2 Enabling Multibyte Characters		Controlling whether to use multibyte characters.
27.3 Language Environments		Setting things up for the language you use.
27.4 Input Methods		Entering text characters not on your keyboard.
27.5 Selecting an Input Method		Specifying your choice of input methods.
27.6 Unibyte and Multibyte Non-ASCII characters		How single-byte characters convert to multibyte.
27.7 Coding Systems		Character set conversion when you read and write files, and so on.
27.8 Recognizing Coding Systems		How Emacs figures out which conversion to use.
27.9 Specifying a File's Coding System		Specifying a file's coding system explicitly.
27.10 Choosing Coding Systems for Output		Choosing coding systems for output.
27.11 Specifying a Coding System for File Text		Choosing conversion to use for file text.
27.12 Coding Systems for Interprocess Communication		Coding systems for interprocess communication.
27.13 Coding Systems for File Names		Coding systems for file names.
27.14 Coding Systems for Terminal I/O		Specifying coding systems for converting terminal input and output.
27.15 Fontsets		Fontsets are collections of fonts that cover the whole spectrum of characters.
27.16 Defining fontsets		Defining a new fontset.
27.17 Undisplayable Characters		When characters don't display.
27.18 Unibyte Editing Mode		You can pick one European character set to use without multibyte characters.
27.19 Charsets		How Emacs groups its internal character codes.

Major Modes

28.1 How Major Modes are Chosen

How major modes are specified or chosen.

Indentation

29.1 Indentation Commands and Techniques		Various commands and techniques for indentation.
29.2 Tab Stops		You can set arbitrary "tab stops" and then indent to the next tab stop when you want to.
29.3 Tabs vs. Spaces		You can request indentation using just spaces.

Commands for Human Languages

30.1 Words		Moving over and killing words.
30.2 Sentences		Moving over and killing sentences.
30.3 Paragraphs		Moving over paragraphs.
30.4 Pages		Moving over pages.
30.5 Filling Text		Filling or justifying text.
30.6 Case Conversion Commands		Changing the case of text.
30.7 Text Mode		The major modes for editing text files.
30.8 Outline Mode		Editing outlines.
30.9 TeX Mode		Editing input to the formatter TeX.
30.10 SGML, XML, and HTML Modes		Editing HTML, SGML, and XML files.
30.11 Nroff Mode		Editing input to the formatter nroff.
30.12 Editing Formatted Text		Editing formatted text directly in WYSIWYG fashion.
30.13 Editing Text-based Tables		Editing text-based tables in WYSIWYG fashion.

Filling Text

30.5.1 Auto Fill Mode		Auto Fill mode breaks long lines automatically.
30.5.5 Refill Mode		Keeping paragraphs filled.
30.5.2 Explicit Fill Commands		Commands to refill paragraphs and center lines.
30.5.3 The Fill Prefix		Filling paragraphs that are indented or in a comment, etc.
30.5.4 Adaptive Filling		How Emacs can determine the fill prefix automatically.
30.5.6 Long Lines Mode		Editing text with very long lines.

Outline Mode

30.8.1 Format of Outlines		What the text of an outline looks like.
30.8.2 Outline Motion Commands		Special commands for moving through outlines.
30.8.3 Outline Visibility Commands		Commands to control what is visible.
30.8.4 Viewing One Outline in Multiple Views		Outlines and multiple views.
30.8.5 Folding Editing		Folding means zooming in on outlines.

TeX Mode

30.9.1 TeX Editing Commands		Special commands for editing in TeX mode.
30.9.2 LaTeX Editing Commands		Additional commands for LaTeX input files.
30.9.3 TeX Printing Commands		Commands for printing part of a file with TeX.
30.9.4 TeX Mode Miscellany		Customization of TeX mode, and related features.

Editing Formatted Text

30.12.1 Requesting to Edit Formatted Text		Entering and exiting Enriched mode.
30.12.2 Hard and Soft Newlines		There are two different kinds of newlines.
30.12.3 Editing Format Information		How to edit text properties.
30.12.4 Faces in Formatted Text		Bold, italic, underline, etc.
30.12.5 Colors in Formatted Text		Changing the color of text.
30.12.6 Indentation in Formatted Text		Changing the left and right margins.
30.12.7 Justification in Formatted Text		Centering, setting text flush with the left or right margin, etc.
30.12.8 Setting Other Text Properties		The "special" text properties submenu.
30.12.9 Forcing Enriched Mode		How to force use of Enriched mode.

Editing Text-based Tables

30.13.1 What is a Text-based Table?		What is a text based table.
30.13.2 How to Create a Table?		How to create a table.
30.13.3 Table Recognition		How to activate and deactivate tables.
30.13.4 Commands for Table Cells		Cell-oriented commands in a table.
30.13.5 Cell Justification		Justifying cell contents.
30.13.6 Commands for Table Rows		Manipulating rows of table cell.
30.13.7 Commands for Table Columns		Manipulating columns of table cell.
30.13.8 Fix Width of Cells		Fixing cell width.
30.13.9 Conversion Between Plain Text and Tables		Converting between plain text and tables.
30.13.10 Analyzing Table Dimensions		Analyzing table dimension.
30.13.11 Table Miscellany		Table miscellany.

Editing Programs

31.1 Major Modes for Programming Languages		Major modes for editing programs.
31.2 Top-Level Definitions, or Defuns		Commands to operate on major top-level parts of a program.
31.3 Indentation for Programs		Adjusting indentation to show the nesting.
31.4 Commands for Editing with Parentheses		Commands that operate on parentheses.
31.5 Manipulating Comments		Inserting, killing, and aligning comments.
31.6 Documentation Lookup		Getting documentation of functions you plan to call.
31.7 Hideshow minor mode		Displaying blocks selectively.
31.8 Completion for Symbol Names		Completion on symbol names of your program or language.
31.9 Glasses minor mode		Making identifiersLikeThis more readable.
31.10 Other Features Useful for Editing Programs		Other Emacs features useful for editing programs.
31.11 C and Related Modes		Special commands of C, C++, Objective-C, Java, and Pike modes.
31.12 Asm Mode		Asm mode and its special features.
31.13 Fortran Mode		Fortran mode and its special features.

Top-Level Definitions, or Defuns

31.2.1 Left Margin Convention		An open-paren or similar opening delimiter starts a defun if it is at the left margin.
31.2.2 Moving by Defuns		Commands to move over or mark a major definition.
31.2.3 Imenu		Making buffer indexes as menus.
31.2.4 Which Function Mode		Which Function mode shows which function you are in.

Indentation for Programs

31.3.1 Basic Program Indentation Commands		Indenting a single line.
31.3.2 Indenting Several Lines		Commands to reindent many lines at once.
31.3.3 Customizing Lisp Indentation		Specifying how each Lisp function should be indented.
31.3.4 Commands for C Indentation		Extra features for indenting C and related modes.
31.3.5 Customizing C Indentation		Controlling indentation style for C and related modes.

Commands for Editing with Parentheses

31.4.1 Expressions with Balanced Parentheses		Expressions with balanced parentheses.
31.4.2 Moving in the Parenthesis Structure		Commands for moving up, down and across in the structure of parentheses.
31.4.3 Automatic Display Of Matching Parentheses		Insertion of a close-delimiter flashes matching open.

Manipulating Comments

31.5.1 Comment Commands		Inserting, killing, and aligning comments.
31.5.2 Multiple Lines of Comments		Commands for adding and editing multi-line comments.
31.5.3 Options Controlling Comments		Customizing the comment features.

Documentation Lookup

31.6.1 Info Documentation Lookup		Looking up library functions and commands in Info files.
31.6.2 Man Page Lookup		Looking up man pages of library functions and commands.
31.6.3 Emacs Lisp Documentation Lookup		Looking up Emacs Lisp functions, etc.

C and Related Modes

31.11.1 C Mode Motion Commands		Commands to move by C statements, etc.
31.11.2 Electric C Characters		Colon and other chars can automatically reindent.
31.11.3 Hungry Delete Feature in C		A more powerful DEL command.
31.11.4 Other Commands for C Mode		Filling comments, viewing expansion of macros, and other neat features.

Compiling and Testing Programs

32.1 Running Compilations under Emacs		Compiling programs in languages other than Lisp (C, Pascal, etc.).
32.2 Compilation Mode		The mode for visiting compiler errors.
32.3 Subshells for Compilation		Customizing your shell properly for use in the compilation buffer.
32.4 Searching with Grep under Emacs		Searching with grep.
32.5 Finding Syntax Errors On The Fly		Finding syntax errors on the fly.
32.6 Running Debuggers Under Emacs		Running symbolic debuggers for non-Lisp programs.
32.7 Executing Lisp Expressions		Various modes for editing Lisp programs, with different facilities for running the Lisp programs.
32.8 Libraries of Lisp Code for Emacs		Creating Lisp programs to run in Emacs.
32.9 Evaluating Emacs Lisp Expressions		Executing a single Lisp expression in Emacs.
32.10 Lisp Interaction Buffers		Executing Lisp in an Emacs buffer.
32.11 Running an External Lisp		Communicating through Emacs with a separate Lisp.

Running Debuggers Under Emacs

32.6.1 Starting GUD		How to start a debugger subprocess.
32.6.2 Debugger Operation		Connection between the debugger and source buffers.
32.6.3 Commands of GUD		Key bindings for common commands.
32.6.4 GUD Customization		Defining your own commands for GUD.
32.6.5 GDB Graphical Interface		An enhanced mode that uses GDB features to implement a graphical debugging environment through Emacs.

Maintaining Large Programs

33.1 Change Logs		Maintaining a change history for your program.
33.2 Format of ChangeLog		What the change log file looks like.
33.3 Tags Tables		Go direct to any function in your program in one command. Tags remembers which file it is in.
33.4 Merging Files with Emerge		A convenient way of merging two versions of a program.

Tags Tables

33.3.1 Source File Tag Syntax		Tag syntax for various types of code and text files.
33.3.2 Creating Tags Tables		Creating a tags table with etags.
33.3.3 Etags Regexps		Create arbitrary tags using regular expressions.
33.3.4 Selecting a Tags Table		How to visit a tags table.
33.3.5 Finding a Tag		Commands to find the definition of a specific tag.
33.3.6 Searching and Replacing with Tags Tables		Using a tags table for searching and replacing.
33.3.7 Tags Table Inquiries		Listing and finding tags defined in a file.

Abbrevs

34.1 Abbrev Concepts		Fundamentals of defined abbrevs.
34.2 Defining Abbrevs		Defining an abbrev, so it will expand when typed.
34.3 Controlling Abbrev Expansion		Controlling expansion: prefixes, canceling expansion.
34.4 Examining and Editing Abbrevs		Viewing or editing the entire list of defined abbrevs.
34.5 Saving Abbrevs		Saving the entire list of abbrevs for another session.
34.6 Dynamic Abbrev Expansion		Abbreviations for words already in the buffer.
34.7 Customizing Dynamic Abbreviation		What is a word, for dynamic abbrevs. Case handling.

Editing Pictures

35.1 Basic Editing in Picture Mode		Basic concepts and simple commands of Picture Mode.
35.2 Controlling Motion after Insert		Controlling direction of cursor motion after "self-inserting" characters.
35.3 Picture Mode Tabs		Various features for tab stops and indentation.
35.4 Picture Mode Rectangle Commands		Clearing and superimposing rectangles.

Sending Mail

36.1 The Format of the Mail Buffer		Format of the mail being composed.
36.2 Mail Header Fields		Details of permitted mail header fields.
36.3 Mail Aliases		Abbreviating and grouping mail addresses.
36.4 Mail Mode		Special commands for editing mail being composed.
36.5 Mail Amusements		Distract the NSA's attention; add a fortune to a msg.
36.6 Mail-Composition Methods		Using alternative mail-composition methods.

Reading Mail with Rmail

37.1 Basic Concepts of Rmail		Basic concepts of Rmail, and simple use.
37.2 Scrolling Within a Message		Scrolling through a message.
37.3 Moving Among Messages		Moving to another message.
37.4 Deleting Messages		Deleting and expunging messages.
37.5 Rmail Files and Inboxes		How mail gets into the Rmail file.
37.6 Multiple Rmail Files		Using multiple Rmail files.
37.7 Copying Messages Out to Files		Copying message out to files.
37.8 Labels		Classifying messages by labeling them.
37.9 Rmail Attributes		Certain standard labels, called attributes.
37.10 Sending Replies		Sending replies to messages you are viewing.
37.11 Summaries		Summaries show brief info on many messages.
37.12 Sorting the Rmail File		Sorting messages in Rmail.
37.13 Display of Messages		How Rmail displays a message; customization.
37.14 Rmail and Coding Systems		How Rmail handles decoding character sets.
37.15 Editing Within a Message		Editing message text and headers in Rmail.
37.16 Digest Messages		Extracting the messages from a digest message.
37.17 Converting an Rmail File to Inbox Format		Converting an Rmail file to mailbox format.
37.18 Reading Rot13 Messages		Reading messages encoded in the rot13 code.
37.19 movemail program		More details of fetching new mail.
37.20 Retrieving Mail from Remote Mailboxes
37.21 Retrieving Mail from Local Mailboxes in Various Formats

Dired, the Directory Editor

38.1 Entering Dired		How to invoke Dired.
38.2 Navigation in the Dired Buffer		How to move in the Dired buffer.
38.3 Deleting Files with Dired		Deleting files with Dired.
38.4 Flagging Many Files at Once		Flagging files based on their names.
38.5 Visiting Files in Dired		Other file operations through Dired.
38.6 Dired Marks vs. Flags		Flagging for deletion vs marking.
38.7 Operating on Files		How to copy, rename, print, compress, etc. either one file or several files.
38.8 Shell Commands in Dired		Running a shell command on the marked files.
38.9 Transforming File Names in Dired		Using patterns to rename multiple files.
38.10 File Comparison with Dired		Running `diff' by way of Dired.
38.11 Subdirectories in Dired		Adding subdirectories to the Dired buffer.
38.12 Subdirectory Switches in Dired		Subdirectory switches in Dired.
38.13 Moving Over Subdirectories		Moving across subdirectories, and up and down.
38.14 Hiding Subdirectories		Making subdirectories visible or invisible.
38.15 Updating the Dired Buffer		Discarding lines for files of no interest.
38.16 Dired and find		Using `find' to choose the files for Dired.
38.17 Editing the Dired Buffer		Operating on files by editing the Dired buffer.
38.18 Viewing Image Thumbnails in Dired		Viewing image thumbnails in Dired
38.19 Other Dired Features		Various other features.

The Calendar and the Diary

39.1 Movement in the Calendar		Moving through the calendar; selecting a date.
39.2 Scrolling in the Calendar		Bringing earlier or later months onto the screen.
39.3 Counting Days		How many days are there between two dates?
39.4 Miscellaneous Calendar Commands		Exiting or recomputing the calendar.
39.5 Writing Calendar Files		Writing calendars to files of various formats.
39.6 Holidays		Displaying dates of holidays.
39.7 Times of Sunrise and Sunset		Displaying local times of sunrise and sunset.
39.8 Phases of the Moon		Displaying phases of the moon.
39.9 Conversion To and From Other Calendars		Converting dates to other calendar systems.
39.10 The Diary		Displaying events from your diary.
39.11 Appointments		Reminders when it's time to do something.
39.12 Importing and Exporting Diary Entries		Converting diary events to/from other formats.
39.13 Daylight Saving Time		How to specify when daylight saving time is active.
39.14 Summing Time Intervals		Keeping track of time intervals.
39.15 Customizing the Calendar and Diary		Advanced Calendar/Diary customization.

Movement in the Calendar

39.1.1 Motion by Standard Lengths of Time		Moving by days, weeks, months, and years.
39.1.2 Beginning or End of Week, Month or Year		Moving to start/end of weeks, months, and years.
39.1.3 Specified Dates		Moving to the current date or another specific date.

Conversion To and From Other Calendars

39.9.1 Supported Calendar Systems

The calendars Emacs understands

     (aside from Gregorian).

39.9.2 Converting To Other Calendars		Converting the selected date to various calendars.
39.9.3 Converting From Other Calendars		Moving to a date specified in another calendar.
39.9.4 Converting from the Mayan Calendar		Moving to a date specified in a Mayan calendar.

The Diary

39.10.1 Displaying the Diary		Viewing diary entries and associated calendar dates.
39.10.2 The Diary File		Entering events in your diary.
39.10.3 Date Formats		Various ways you can specify dates.
39.10.4 Commands to Add to the Diary		Commands to create diary entries.
39.10.5 Special Diary Entries		Anniversaries, blocks of dates, cyclic entries, etc.

Gnus

40.1 Gnus Buffers		The group, summary, and article buffers.
40.2 When Gnus Starts Up		What you should know about starting Gnus.
40.3 Summary of Gnus Commands		A short description of the basic Gnus commands.

Running Shell Commands from Emacs

41.1 Single Shell Commands		How to run one shell command and return.
41.2 Interactive Inferior Shell		Permanent shell taking input via Emacs.
41.3 Shell Mode		Special Emacs commands used with permanent shell.
41.4 Shell Prompts		Two ways to recognize shell prompts.
41.5 Shell Command History		Repeating previous commands in a shell buffer.
41.6 Directory Tracking		Keeping track when the subshell changes directory.
41.7 Shell Mode Options		Options for customizing Shell mode.
41.8 Emacs Terminal Emulator		An Emacs window as a terminal emulator.
41.9 Term Mode		Special Emacs commands used in Term mode.
41.10 Page-At-A-Time Output		Paging in the terminal emulator.
41.11 Remote Host Shell		Connecting to another computer.

Using Emacs as a Server

42.1 Invoking emacsclient

Emacs client startup options.

Printing Hard Copies

44. PostScript Hardcopy		Printing buffers or regions as PostScript.
45. Variables for PostScript Hardcopy		Customizing the PostScript printing commands.
46. Printing Package		An optional advanced printing interface.

Hyperlinking and Navigation Features

54.1 Following URLs
54.2 Activating URLs
54.3 Finding Files and URLs at Point		Finding files etc. at point.

Customization

57.1 Minor Modes		Each minor mode is one feature you can turn on independently of any others.
57.2 Easy Customization Interface		Convenient way to browse and change user options.
57.3 Variables		Many Emacs commands examine Emacs variables to decide what to do; by setting variables, you can control their functioning.
57.4 Customizing Key Bindings		The keymaps say what command each key runs. By changing them, you can "redefine keys".
57.5 The Syntax Table		The syntax table controls how words and expressions are parsed.
57.6 The Init File, `~/.emacs'		How to write common customizations in the

  `.emacs' file.

Variables

57.3.1 Examining and Setting Variables		Examining or setting one variable's value.
57.3.2 Hooks		Hook variables let you specify programs for parts of Emacs to run on particular occasions.
57.3.3 Local Variables		Per-buffer values of variables.
57.3.4 Local Variables in Files		How files can specify variable values.

Customizing Key Bindings

57.4.1 Keymaps		Generalities. The global keymap.
57.4.2 Prefix Keymaps		Keymaps for prefix keys.
57.4.3 Local Keymaps		Major and minor modes have their own keymaps.
57.4.4 Minibuffer Keymaps		The minibuffer uses its own local keymaps.
57.4.5 Changing Key Bindings Interactively		How to redefine one key's meaning conveniently.
57.4.6 Rebinding Keys in Your Init File		Rebinding keys with your init file, `.emacs'.
57.4.7 Rebinding Function Keys		Rebinding terminal function keys.
57.4.8 Named ASCII Control Characters		Distinguishing TAB from C-i, and so on.
57.4.9 Rebinding Mouse Buttons		Rebinding mouse buttons in Emacs.
57.4.10 Disabling Commands		Disabling a command means confirmation is required before it can be executed. This is done to protect beginners from surprises.

The Init File, `~/.emacs'

57.6.1 Init File Syntax		Syntax of constants in Emacs Lisp.
57.6.2 Init File Examples		How to do some things with an init file.
57.6.3 Terminal-specific Initialization		Each terminal type can have an init file.
57.6.4 How Emacs Finds Your Init File		How Emacs finds the init file.
57.6.5 Non-ASCII Characters in Init Files		Using non-ASCII characters in an init file.

Dealing with Emacs Trouble

59.1 If DEL Fails to Delete		What to do if DEL doesn't delete.
59.2 Recursive Editing Levels		`[...]' in mode line around the parentheses.
59.3 Garbage on the Screen		Garbage on the screen.
59.4 Garbage in the Text		Garbage in the text.
59.5 Running out of Memory		How to cope when you run out of memory.
59.6 Recovery After a Crash		Recovering editing in an Emacs session that crashed.
59.7 Emergency Escape		Emergency escape--- What to do if Emacs stops responding.
59.8 Help for Total Frustration		When you are at your wits' end.

Reporting Bugs

60.1 When Is There a Bug		Have you really found a bug?
60.2 Understanding Bug Reporting		How to report a bug effectively.
60.3 Checklist for Bug Reports		Steps to follow for a good bug report.
60.4 Sending Patches for GNU Emacs		How to send a patch for GNU Emacs.

Command Line Arguments for Emacs Invocation

C.1 Action Arguments		Arguments to visit files, load libraries, and call functions.
C.2 Initial Options		Arguments that take effect while starting Emacs.
C.3 Command Argument Example		Examples of using command line arguments.
C.4 Resuming Emacs with Arguments		Specifying arguments when you resume a running Emacs.
C.5 Environment Variables		Environment variables that Emacs uses.
C.6 Specifying the Display Name		Changing the default display and using remote login.
C.7 Font Specification Options		Choosing a font for text, under X.
C.8 Window Color Options		Choosing display colors.
C.9 Options for Window Size and Position		Start-up window size, under X.
C.10 Internal and External Borders		Internal and external borders, under X.
C.11 Frame Titles		Specifying the initial frame's title.
C.12 Icons		Choosing what sort of icon to use, under X.
C.13 Other Display Options		Other display options.

Environment Variables

C.5.1 General Variables		Environment variables that all versions of Emacs use.
C.5.2 Miscellaneous Variables		Certain system specific variables.
C.5.3 The MS-Windows System Registry		An alternative to the environment on MS-Windows.

X Options and Resources

D.1 X Resources		Using X resources with Emacs (in general).
D.2 Table of X Resources for Emacs		Table of specific X resources that affect Emacs.
D.3 X Resources for Faces		X resources for customizing faces.
D.4 Lucid Menu X Resources		X resources for Lucid menus.
D.5 LessTif Menu X Resources		X resources for LessTif and Motif menus.
D.6 GTK resources		Resources for GTK widgets.

Emacs and Mac OS

F.1 Keyboard and Mouse Input on Mac		Keyboard and mouse input on Mac.
F.2 International Character Set Support on Mac		International character sets on Mac.
F.3 Environment Variables and Command Line Arguments.		Setting environment variables for Emacs.
F.4 Volumes and Directories on Mac		Volumes and directories on Mac.
F.5 Specifying Fonts on Mac		Specifying fonts on Mac.
F.6 Mac-Specific Lisp Functions		Mac-specific Lisp functions.

Emacs and Microsoft Windows/MS-DOS

G.1 Text Files and Binary Files		Text files use CRLF to terminate lines.
G.2 File Names on MS-Windows		File-name conventions on Windows.
G.3 Emulation of ls on MS-Windows		Emulation of ls for Dired.
G.4 HOME Directory on MS-Windows		Where Emacs looks for your `.emacs'.
G.5 Keyboard Usage on MS-Windows		Windows-specific keyboard features.
G.6 Mouse Usage on MS-Windows		Windows-specific mouse features.
G.7 Subprocesses on Windows 9X/ME and Windows NT/2K/XP		Running subprocesses on Windows.
G.8 Printing and MS-Windows		How to specify the printer on MS-Windows.
G.9 Miscellaneous Windows-specific features		Miscellaneous Windows features.
G.10 Emacs and MS-DOS		Using Emacs on MS-DOS (otherwise known as MS-DOG).

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). See section A. GNU GENERAL PUBLIC LICENSE.

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.

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. See section 11. 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 (see section 31.5 Manipulating 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. See section 57. 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. See section `Preface' in An Introduction to Programming in Emacs Lisp, 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. See section 26. Frames and Graphical Displays.

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 (see section 25. Multiple 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		The place in the text where editing commands operate.
1.2 The Echo Area		Short messages appear at the bottom of the screen.
1.3 The Mode Line		Interpreting the mode line.
1.4 The Menu Bar		How to use the menu bar.

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.

See section 19.15 Displaying the Cursor, 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 (see section 19.17 Customization of Display).

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 CTRL and type x, then let go of CTRL 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 24. Using Multiple 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. See section 57.3 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. See section 9. The 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 19.13 Optional Mode Line Features, 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 (see section 26. Frames and Graphical Displays). 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. See section 24. Using Multiple 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. See section 19.13 Optional Mode Line Features.

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. See section 19.13 Optional Mode Line Features.

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. See section 28. 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. See section 57.1 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.) See section 48. Narrowing. `Def' means that a keyboard macro is being defined. See section 22. 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. See section 52. Recursive Editing Levels.

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. See section 27.7 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 `>'.) See section 27.4 Input Methods.

When multibyte characters are not enabled, cs does not appear at all. See section 27.2 Enabling Multibyte Characters.

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.

See section 19.13 Optional Mode Line Features, 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. See section 26.4 Mode Line Mouse Commands.

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 F10 (to run the command menu-bar-open). You can then navigate the menus with the arrow keys. You select an item by pressing RET and cancel menu navigation with ESC.

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 (see section 11.2 Documentation for a Key).

On text-only terminals with no mouse, you can use the menu bar by typing M-` or F10 (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 RET 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 CTRL key while pressing a.

Some ASCII control characters have special names, and most terminals have special keys you can type them with: for example, RET, TAB, DEL and ESC. The space character is usually known as SPC, even though strictly speaking it is a graphic character that is blank.

Emacs extends the ASCII character set with thousands more printing characters (see section 27. International Character Set Support), 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-RET, and M-C-a. That last means a with both the CTRL and META modifiers. We usually write it as C-M-a rather than M-C-a, for reasons of tradition.

Some terminals have a META key, and allow you to type Meta characters by holding this key down. Thus, you can type Meta-a by holding down META and pressing a. The META key works much like the SHIFT key. In fact, this key is more often labeled ALT or EDIT, instead of META; on a Sun keyboard, it may have a diamond on it.

If there is no META key, you can still type Meta characters using two-character sequences starting with ESC. Thus, you can enter M-a by typing ESC a. You can enter C-M-a by typing ESC C-a. Unlike META, which modifies other characters, ESC is a separate character. You don't hold down ESC while typing the next character; instead, you press it and release it, then you enter the next character. ESC is allowed on terminals with META 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 SUPER, HYPER and ALT. 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 ALT which is really a META 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 CTRL, META, SUPER, HYPER and ALT, just like keyboard characters.

Input characters and non-character inputs are collectively called input events. See section `Input Events' in The Emacs Lisp Reference Manual, 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 57. 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-TAB before Emacs can see it. It may also block Meta-SPC, 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, RET, NEXT (a function key), DOWN (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 RET, C-x @, C-x a, C-x n, C-x r, C-x v, C-x 4, C-x 5, C-x 6, ESC, M-g, and M-o. (F1 and F2 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). See section 57.4 Customizing 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 F1) 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. F1 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 section `What Is a Function' in The Emacs Lisp Reference Manual. (The definition here is simplified slightly.)

The bindings between keys and commands are recorded in tables called keymaps. See section 57.4.1 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 (see section 57.3 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. See section 27. International Character Set Support. 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). See section 19.14 How Text Is Displayed.

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. See section 27.18 Unibyte Editing 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. See section 57.6 The Init File, `~/.emacs'.

It is possible to specify files to be visited, Lisp files to be loaded, and functions to be called through Emacs command-line arguments. See section C. Command Line Arguments for 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. See section 23. File Handling, 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. See section 42. Using Emacs as a 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 (see section 26. Frames and Graphical Displays). 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. See section 51. 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 (see section 57.4.1 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		Inserting text by simply typing it.
8.2 Changing the Location of Point		Moving the cursor to the place where you want to change something.
8.3 Erasing Text		Deleting and killing text.
8.4 Undoing Changes		Undoing recent changes in the text.
8.5 Files		Visiting, creating, and saving files.
8.6 Help		Asking what a character does.
8.7 Blank Lines		Making and deleting blank lines.
8.8 Continuation Lines		How Emacs displays lines too wide for the screen.
8.9 Cursor Position Information		What page, line, row, or column is point on?
8.10 Numeric Arguments		Numeric arguments for repeating a command N times.
8.11 Repeating a Command		Repeating the previous command quickly.

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. See section 1.1 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 DEL, BACKSPACE or DELETE which is a short distance above the RET or ENTER key. Regardless of the label on that key, Emacs thinks of it as DEL, and that's what we call it in this manual. DEL is the key you normally use outside Emacs to erase the last character that you typed.

The DEL 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 DEL, they cancel out.

On most computers, Emacs sets up DEL 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 59.1 If DEL Fails to Delete.

Most PC keyboards have both a BACKSPACE key a little ways above RET or ENTER, and a DELETE key elsewhere. On these keyboards, Emacs tries to set up BACKSPACE as DEL. The DELETE 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 RET. (This key may be labeled RETURN or ENTER, but in Emacs we call it RET.) 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 DEL 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. See section 30.5 Filling Text, 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. See section 57.1 Minor Modes.

Only printing characters and SPC 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 RET, 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. See section 27.2 Enabling Multibyte Characters. You select which of the ISO 8859 character sets to use through your choice of language environment (see section 27.3 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 (see section 8.10 Numeric Arguments).

Customization information: DEL in most modes runs the command delete-backward-char; RET runs the command newline, and self-inserting printing characters run the command self-insert, which inserts whatever character you typed. Some major modes rebind DEL to other commands.

8.2 Changing the Location of Point

To do more than insert characters, you have to know how to move point (see section 1.1 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. See section 8.10 Numeric Arguments, for more information on numeric arguments.

M->

Move to the end of the buffer (end-of-buffer).

C-v

PAGEDOWN

PRIOR

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 PAGEDOWN or PRIOR key, it does the same thing.

Scrolling commands are described further in 19.1 Scrolling.

M-v

PAGEUP

NEXT

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 PAGEUP or NEXT 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 RET 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. See section 57.3 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

DEL

Delete the character before point (delete-backward-char).

C-d

Delete the character after point (delete-char).

DELETE

BACKSPACE

One of these keys, whichever is the large key above the RET or ENTER key, deletes the character before point--it is DEL. If BACKSPACE is DEL, and your keyboard also has DELETE, then DELETE 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-DEL

Kill back to the beginning of the previous word (backward-kill-word).

You already know about the DEL 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.

See section 13. Killing and Moving Text, 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 (see section 12.6 The 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 RET

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 RET to terminate the argument (see section 9. The 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 23. File Handling.

8.6 Help

If you forget what a key does, you can find out with the Help character, which is C-h (or F1, 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. See section 11. 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 RET. 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 RET, 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. See section 8.10 Numeric 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. See section 30.5.3 The 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. See section 30.5 Filling Text.

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.

See section 19.16 Truncation of Lines, 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. See section 19.13 Optional Mode Line Features.

M-=

Display the number of lines in the current region (count-lines-region). See section 12. The Mark and the Region, 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. See section 19.15 Displaying the Cursor.

M-x size-indication-mode

Toggle automatic display of the size of the buffer. See section 19.13 Optional Mode Line Features.

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 1.3 The Mode Line; but if you narrow the buffer, the line number in the mode line is relative to the accessible portion (see section 48. 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. See section 30.4 Pages.

Use M-= (count-lines-region) to displays the number of lines in the region (see section 12. The Mark and the Region). See section 30.4 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 (see section 27.7 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. See section 48. 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 (see section `Text Properties' in the Emacs Lisp Reference Manual), and any overlays containing it (see section `Overlays' in the same manual).

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 `À'), and which has font-lock-mode (see section 19.7 Font Lock mode) enabled:

character: À (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 META key (labeled ALT on PC keyboards), the easiest way to specify a numeric argument is to type digits and/or a minus sign while holding down the META 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. (See section 30.5 Filling Text, 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. (See section 13. Killing and Moving Text, 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 RET, can be repeated by invoking them with a numeric argument that serves as a repeat count (see section 8.10 Numeric 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 RET. For example, commands that read buffer names show a buffer name as the default. You can type RET to operate on that default buffer.

The simplest way to enter a minibuffer argument is to type the text, then RET 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		Entering file names with the minibuffer.
9.2 Editing in the Minibuffer		How to edit in the minibuffer.
9.3 Completion		An abbreviation facility for minibuffer input.
9.4 Minibuffer History		Reusing recent minibuffer arguments.
9.5 Repeating Minibuffer Commands		Re-executing commands that used the minibuffer.

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-DEL to kill the directory names you don't want (see section 30.1 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 RET 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. See section 25. Multiple 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-PAGEUP and M-PAGEDOWN also operate on that help text. This is especially useful with long lists of possible completions. See section 25.3 Using Other Windows.

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

When completion is available, certain keys---TAB, RET, and SPC---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. (SPC 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 SPC b RET instead of M-x insert-buffer RET, 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		Examples of using completion.
9.3.2 Completion Commands		A list of completion commands.
9.3.3 Strict Completion		Different types of completion.
9.3.4 Completion Options		Options for completion.

9.3.1 Completion Example

A concrete example may help here. If you type M-x au TAB, the TAB 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 TAB again immediately, it cannot determine the next character; it could be any of `cfilrs'. So it does not add any characters; instead, TAB displays a list of all possible completions in another window.

Now type f TAB. This TAB 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 TAB f TAB.

9.3.2 Completion Commands

Here is a list of the completion commands defined in the minibuffer when completion is allowed.

TAB

Complete the text before point in the minibuffer as much as possible (minibuffer-complete).

SPC

Complete up to one word from the minibuffer text before point (minibuffer-complete-word). SPC for completion is not available when entering a file name, since file names often include spaces.

RET

Submit the text in the minibuffer as the argument, possibly completing first as described in the next node (minibuffer-complete-and-exit). See section 9.3.3 Strict Completion.

?

Display a list of possible completions of the text before point (minibuffer-completion-help).

SPC completes like TAB, but only up to the next hyphen or space. If you have `auto-f' in the minibuffer and type SPC, it finds that the completion is `auto-fill-mode', but it only inserts `ill-', giving `auto-fill-'. Another SPC 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.

PRIOR

M-v

Typing PRIOR or PAGE-UP, 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.)

RET

Typing RET 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.

RIGHT

Typing the right-arrow key RIGHT in the completion list buffer moves point to the following completion possibility (next-completion).

LEFT

Typing the left-arrow key LEFT 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 RET 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, RET 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 RET exits only if the text is an already exact match. Otherwise, RET does not exit, but it does complete the text. If that completes to an exact match, a second RET 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, RET 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 (see section 25.3 Using Other Windows).

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 TAB, SPC, RET, and ? in the minibuffer. The usual completion commands are available on M-TAB (or C-M-i), M-SPC, M-RET 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. See section 23.15 Remote Files.

Partial Completion mode also extends find-file so that `<include>' 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.

UP

M-p

Move to the previous item in the minibuffer history, an earlier argument (previous-history-element).

DOWN

M-n

Move to the next item in the minibuffer history (next-history-element).

M-r regexp RET

Move to an earlier item in the minibuffer history that matches regexp (previous-matching-history-element).

M-s regexp RET

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 RET. 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 (see section 20.8 Searching and 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 ESC ESC

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 ESC ESC can repeat, most recent first.

C-x ESC ESC 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 ESC ESC 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 RET, 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 ESC ESC, you can use the minibuffer history commands (M-p, M-n, M-r, M-s; see section 9.4 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 RET.

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 ESC ESC. You can make incremental search commands appear in the history by setting isearch-resume-in-command-history to a non-nil value. See section 20.1 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. (See section 57.4 Customizing 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 RET. 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. RET exits the minibuffer and runs the command. See section 9. The 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 RET

or

M-x forw TAB c RET

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 RET that terminates the name. Thus we might say M-x auto-fill-mode rather than M-x auto-fill-mode RET. We mention the RET 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 F1 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 SPC and DEL, then type the help option you want. To cancel, type C-g.

C-h or F1 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 F1 for help.)

Most help buffers use a special major mode, Help mode, which lets you scroll conveniently with SPC and DEL. You can also follow hyperlinks to URLs, and to other facilities including Info nodes and customization buffers. See section 11.5 Help Mode Commands.

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 RET

This searches for commands whose names match the argument topics. The argument can be a keyword, a list of keywords, or a regular expression (see section 20.5 Syntax of Regular Expressions). This command displays all the matches in a new buffer. See section 11.4 Apropos.

C-h i d m emacs RET i topic RET

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 RET s topic RET

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. See section 11.6 Keyword Search for Lisp Libraries.

11.1 Help Summary		Brief list of all Help commands.
11.2 Documentation for a Key		Asking what a key does in Emacs.
11.3 Help by Command or Variable Name		Asking about a command, variable or function name.
11.4 Apropos		Asking what pertains to a given topic.
11.5 Help Mode Commands		Special features of Help mode and Help buffers.
11.6 Keyword Search for Lisp Libraries		Finding Lisp libraries by keywords (topics).
11.7 Help for International Language Support		Help relating to international language support.
11.8 Other Help Commands		Other help commands.
11.9 Help Files		Commands to display pre-written help files.
11.10 Help on Active Text and Tooltips		Help on active text and tooltips (`balloon help')

11.1 Help Summary

Here is a summary of the Emacs interactive help commands. (The character that follows C-h is the "help option.") See section 11.9 Help Files, for other help commands that display fixed files of information.

C-h a topics RET

Display a list of commands whose names match topics (apropos-command; see section 11.4 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 RET

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 RET

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). See section 57.5 The Syntax Table.

C-h t

Enter the Emacs interactive tutorial (help-with-tutorial).

C-h v var RET

Display the documentation of the Lisp variable var (describe-variable).

C-h w command RET

Show which keys run the command named command (where-is).

C-h C coding RET

Describe the coding system coding (describe-coding-system).

C-h C RET

Describe the coding systems currently in use.

C-h I method RET

Describe the input method method (describe-input-method).

C-h L language-env RET

Display information on the character sets, coding systems, and input methods used in language environment language-env (describe-language-environment).

C-h F function RET

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 RET

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 RET 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 RET (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 RET

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 RET. 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 RET, 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 RET 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. See section 57.3 Variables.

Help buffers that describe Emacs variables and functions normally have hyperlinks to the corresponding source definition, if you have the source files installed. (See section 54. Hyperlinking and Navigation Features.) 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 RET

Search for commands whose names match pattern.

M-x apropos RET pattern RET

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 RET pattern RET

Search for user-option variables whose names match pattern.

M-x apropos-value RET pattern RET

Search for functions whose definitions pattern, and variables whose values match pattern.

C-h d pattern RET

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 RET. 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 RET.

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 RET. 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 (see section 20.5 Syntax of Regular Expressions). 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 (see section 23.12 Miscellaneous File Operations), plus a few special commands of their own.

SPC

Scroll forward.

DEL

Scroll backward.

RET

Follow a cross reference at point.

TAB

Move point forward to the next cross reference.

S-TAB

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 (see section Running Commands by Name), variable name (see section 57.3 Variables), or face name (see section 19.5 Using Multiple Typefaces) 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 RET. 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. See section 54.1 Following URLs.

There are convenient commands to move point to cross references in the help text. TAB (help-next-ref) moves point down to the next cross reference. S-TAB 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. See section 27.3 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 this language environment, and finally shows some sample text to illustrate scripts.

The command C-h h (view-hello-file) displays the file `etc/HELLO', which shows how to say "hello" in many languages.

The command C-h I (describe-input-method) describes an input method--either a specified input method, or by default the input method currently in use. See section 27.4 Input Methods.

The command C-h C (describe-coding-system) describes coding systems--either a specified coding system, or the ones currently in use. See section 27.7 Coding Systems.

11.8 Other Help Commands

C-h i (info) runs the Info program, which browses structured documentation files. The entire Emacs manual is available within Info, along with many other manuals for the GNU system. Type h after entering Info to run a tutorial on using Info.

With a numeric argument n, C-h i selects the Info buffer `*info*<n>'. This is useful if you want to browse multiple Info manuals simultaneously. If you specify just C-u as the prefix argument, C-h i prompts for the name of a documentation file, so you can browse a file which doesn't have an entry in the top-level Info menu.

The help commands C-h F function RET and C-h K key, described above, enter Info and go straight to the documentation of function or key.

When editing a program, if you have an Info version of the manual for the programming language, you can use C-h S (info-lookup-symbol) to find symbol (keyword, function or variable) in the proper manual. The details of how this command works depend on the major mode.

If something surprising happens, and you are not sure what you typed, use C-h l (view-lossage). C-h l displays the last 100 characters you typed in Emacs. If you see commands that you don't know, you can use C-h c to find out what they do.

To review recent echo area messages, use C-h e (view-echo-area-messages). This displays the buffer *Messages*, where those messages are kept.

Each Emacs major mode typically redefines a few keys and makes other changes in how editing works. C-h m (describe-mode) displays documentation on the current major mode, which normally describes the commands and features that are changed in this mode.

C-h b (describe-bindings) and C-h s (describe-syntax) show other information about the current environment within Emacs. C-h b displays a list of all the key bindings now in effect: first the local bindings of the current minor modes, then the local bindings defined by the current major mode, and finally the global bindings (see section 57.4 Customizing Key Bindings). C-h s displays the contents of the syntax table, with explanations of each character's syntax (see section 57.5 The Syntax Table).

You can get a list of subcommands for a particular prefix key by typing C-h after the prefix key. (There are a few prefix keys for which this does not work--those that provide their own bindings for C-h. One of these is ESC, because ESC C-h is actually C-M-h, which marks a defun.)

11.9 Help Files

The Emacs help commands described above display dynamic help based on the current state within Emacs, or refer to manuals. Other help commands display pre-written, static help files. These commands all have the form C-h C-char; that is, C-h followed by a control character.

C-h C-c

Display the Emacs copying conditions (describe-copying). These are the rules under which you can copy and redistribute Emacs.

C-h C-d

Display how to download or order the latest version of Emacs and other GNU software (describe-distribution).

C-h C-e

Display the list of known Emacs problems, sometimes with suggested workarounds (view-emacs-problems).

C-h C-f

Display the Emacs frequently-answered-questions list (view-emacs-FAQ).

C-h C-n

Display the Emacs "news" file, which lists new features in the most recent version of Emacs (view-emacs-news).

C-h C-p

Display general information about the GNU Project (describe-project).

C-h C-t

Display the Emacs to-do list (view-todo).

C-h C-w

Display the full details on the complete absence of warranty for GNU Emacs (describe-no-warranty).

11.10 Help on Active Text and Tooltips

When a region of text is "active," so that you can select it with the mouse or a key like RET, it often has associated help text. For instance, most parts of the mode line have help text. On graphical displays, the help text is displayed as a "tooltip" (sometimes known as "balloon help"), when you move the mouse over the active text. See section 26.17 Tooltips. On some systems, it is shown in the echo area. On text-only terminals, if Emacs cannot follow the mouse, it cannot show the help text on mouse-over.

You can also access text region help info using the keyboard. The command C-h . (display-local-help) displays any help text associated with the text at point, using the echo area. If you want help text to be displayed automatically whenever it is available at point, set the variable help-at-pt-display-when-idle to t.

12. The Mark and the Region

Many Emacs commands operate on an arbitrary contiguous part of the current buffer. To specify the text for such a command to operate on, you set the mark at one end of it, and move point to the other end. The text between point and the mark is called the region. Emacs highlights the region whenever there is one, if you enable Transient Mark mode (see section 12.2 Transient Mark Mode).

Certain Emacs commands set the mark; other editing commands do not affect it, so the mark remains where you set it last. Each Emacs buffer has its own mark, and setting the mark in one buffer has no effect on other buffers' marks. When you return to a buffer that was current earlier, its mark is at the same place as before.

The ends of the region are always point and the mark. It doesn't matter which of them was put in its current place first, or which one comes earlier in the text--the region starts from point or the mark (whichever comes first), and ends at point or the mark (whichever comes last). Every time you move point, or set the mark in a new place, the region changes.

Many commands that insert text, such as C-y (yank) and M-x insert-buffer, position point and the mark at opposite ends of the inserted text, so that the region consists of the text just inserted.

Aside from delimiting the region, the mark is also useful for remembering a spot that you may want to go back to. To make this feature more useful, each buffer remembers 16 previous locations of the mark in the mark ring.

12.1 Setting the Mark		Commands to set the mark.
12.2 Transient Mark Mode		How to make Emacs highlight the region-- when there is one.
12.3 Using Transient Mark Mode Momentarily		Enabling Transient Mark mode momentarily.
12.4 Operating on the Region		Summary of ways to operate on contents of the region.
12.5 Commands to Mark Textual Objects		Commands to put region around textual units.
12.6 The Mark Ring		Previous mark positions saved so you can go back there.
12.7 The Global Mark Ring		Previous mark positions in various buffers.

12.1 Setting the Mark

Here are some commands for setting the mark:

C-SPC

Set the mark where point is (set-mark-command).

C-@

The same.

C-x C-x

Interchange mark and point (exchange-point-and-mark).

Drag-Mouse-1

Set point and the mark around the text you drag across.

Mouse-3

Set the mark where point is, then move point to where you click (mouse-save-then-kill).

For example, suppose you wish to convert part of the buffer to upper case, using the C-x C-u (upcase-region) command, which operates on the text in the region. You can first go to the beginning of the text to be capitalized, type C-SPC to put the mark there, move to the end, and then type C-x C-u. Or, you can set the mark at the end of the text, move to the beginning, and then type C-x C-u.

The most common way to set the mark is with the C-SPC command (set-mark-command). This sets the mark where point is. Then you can move point away, leaving the mark behind.

There are two ways to set the mark with the mouse. You can drag mouse button one across a range of text; that puts point where you release the mouse button, and sets the mark at the other end of that range. Or you can click mouse button three, which sets the mark at point (like C-SPC) and then moves point where you clicked (like Mouse-1).

Using the mouse to mark a region copies the region into the kill ring in addition to setting the mark; that gives behavior consistent with other window-driven applications. If you don't want to modify the kill ring, you must use keyboard commands to set the mark. See section 26.1.1 Mouse Commands for Editing.

When Emacs was developed, terminals had only one cursor, so Emacs does not show where the mark is located--you have to remember. If you enable Transient Mark mode (see below), then the region is highlighted when it is active; you can tell mark is at the other end of the highlighted region. But this only applies when the mark is active.

The usual solution to this problem is to set the mark and then use it soon, before you forget where it is. Alternatively, you can see where the mark is with the command C-x C-x (exchange-point-and-mark) which puts the mark where point was and point where the mark was. The extent of the region is unchanged, but the cursor and point are now at the previous position of the mark. In Transient Mark mode, this command also reactivates the mark.

C-x C-x is also useful when you are satisfied with the position of point but want to move the other end of the region (where the mark is); do C-x C-x to put point at that end of the region, and then move it. Using C-x C-x a second time, if necessary, puts the mark at the new position with point back at its original position.

For more facilities that allow you to go to previously set marks, see 12.6 The Mark Ring.

There is no such character as C-SPC in ASCII; when you type SPC while holding down CTRL on a text terminal, what you get is the character C-@. This key is also bound to set-mark-command--so unless you are unlucky enough to have a text terminal where typing C-SPC does not produce C-@, you might as well think of this character as C-SPC.

12.2 Transient Mark Mode

On a terminal that supports colors, Emacs has the ability to highlight the current region. But normally it does not. Why not?

In the normal mode of use, every command that sets the mark also activates it, and nothing ever deactivates it. Thus, once you have set the mark in a buffer, there is always a region in that buffer. Highlighting the region all the time would be a nuisance. So normally Emacs highlights the region only immediately after you have selected one with the mouse.

If you want region highlighting, you can use Transient Mark mode. This is a more rigid mode of operation in which the region "lasts" only until you use it; operating on the region text deactivates the mark, so there is no region any more. Therefore, you must explicitly set up a region for each command that uses one.

When Transient Mark mode is enabled, Emacs highlights the region, whenever there is a region. In Transient Mark mode, most of the time there is no region; therefore, highlighting the region when it exists is useful and not annoying.

To enable Transient Mark mode, type M-x transient-mark-mode. This command toggles the mode; you can use the same command to turn the mode off again.

Here are the details of Transient Mark mode:

• To set the mark, type C-SPC (set-mark-command). This makes the mark active and thus begins highlighting of the region. As you move point, you will see the highlighted region grow and shrink.

• The mouse commands for specifying the mark also make it active. So do keyboard commands whose purpose is to specify a region, including M-@, C-M-@, M-h, C-M-h, C-x C-p, and C-x h.

• You can tell that the mark is active because the region is highlighted.

• When the mark is active, you can execute commands that operate on the region, such as killing, indenting, or writing to a file.

• Any change to the buffer, such as inserting or deleting a character, deactivates the mark. This means any subsequent command that operates on a region will get an error and refuse to operate. You can make the region active again by typing C-x C-x.

• If Delete Selection mode is also enabled, some commands delete the region when used while the mark is active. See section 26.1.1 Mouse Commands for Editing.

• Quitting with C-g deactivates the mark.

• Commands like M-> and C-s, that "leave the mark behind" in addition to some other primary purpose, do not activate the new mark. You can activate the new region by executing C-x C-x (exchange-point-and-mark).

• Commands that normally set the mark before moving long distances (like M-< and C-s) do not alter the mark in Transient Mark mode when the mark is active.

• Some commands operate on the region if a region is active. For instance, C-x u in Transient Mark mode operates on the region, when there is a region. (Outside Transient Mark mode, you must type C-u C-x u if you want it to operate on the region.) See section 21.1 Undo. Other commands that act this way are identified in their own documentation.

The highlighting of the region uses the region face; you can customize the appearance of the highlighted region by changing this face. See section 57.2.5 Customizing Faces.

When multiple windows show the same buffer, they can have different regions, because they can have different values of point (though they all share one common mark position). Ordinarily, only the selected window highlights its region (see section 25. Multiple Windows). However, if the variable highlight-nonselected-windows is non-nil, then each window highlights its own region (provided that Transient Mark mode is enabled and the mark in the window's buffer is active).

If the variable mark-even-if-inactive is non-nil in Transient Mark mode, then commands can use the mark and the region even when it is inactive. Region highlighting appears and disappears just as it normally does in Transient Mark mode, but the mark doesn't really go away when the highlighting disappears, so you can still use region commands.

Transient Mark mode is also sometimes known as "Zmacs mode" because the Zmacs editor on the MIT Lisp Machine handled the mark in a similar way.

12.3 Using Transient Mark Mode Momentarily

If you don't like Transient Mark mode in general, you might still want to use it once in a while. To do this, type C-SPC C-SPC or C-u C-x C-x. These commands set or activate the mark, and enable Transient Mark mode only until the mark is deactivated.

C-SPC C-SPC

Set the mark at point (like plain C-SPC), and enable Transient Mark mode just once until the mark is deactivated. (This is not really a separate command; you are using the C-SPC command twice.)

C-u C-x C-x

Activate the mark without changing it; enable Transient Mark mode just once, until the mark is deactivated. (This is the C-x C-x command, exchange-point-and-mark, with a prefix argument.)

One of the secondary features of Transient Mark mode is that certain commands operate only on the region, when there is an active region. If you don't use Transient Mark mode, the region once set never becomes inactive, so there is no way for these commands to make such a distinction. Enabling Transient Mark mode momentarily gives you a way to use these commands on the region.

Momentary use of Transient Mark mode is also a way to highlight the region for the time being.

12.4 Operating on the Region

Once you have a region and the mark is active, here are some of the ways you can operate on the region:

• Kill it with C-w (see section 13. Killing and Moving Text).
• Save it in a register with C-x r s (see section 18. Registers).
• Save it in a buffer or a file (see section 15. Accumulating Text).
• Convert case with C-x C-l or C-x C-u (see section 30.6 Case Conversion Commands).
• Indent it with C-x TAB or C-M-\ (see section 29. Indentation).
• Fill it as text with M-x fill-region (see section 30.5 Filling Text).
• Print hardcopy with M-x print-region (see section 43. Printing Hard Copies).
• Evaluate it as Lisp code with M-x eval-region (see section 32.9 Evaluating Emacs Lisp Expressions).
• Undo changes within it using C-u C-x u (see section 21.1 Undo).

Most commands that operate on the text in the region have the word region in their names.

12.5 Commands to Mark Textual Objects

Here are the commands for placing point and the mark around a textual object such as a word, list, paragraph or page.

M-@

Set mark after end of next word (mark-word). This command and the following one do not move point.

C-M-@

Set mark after end of following balanced expression (mark-sexp).

M-h

Put region around current paragraph (mark-paragraph).

C-M-h

Put region around current defun (mark-defun).

C-x h

Put region around the entire buffer (mark-whole-buffer).

C-x C-p

Put region around current page (mark-page).

M-@ (mark-word) puts the mark at the end of the next word, while C-M-@ (mark-sexp) puts it at the end of the next balanced expression (see section 31.4.1 Expressions with Balanced Parentheses). These commands handle arguments just like M-f and C-M-f. Repeating these commands extends the region. For example, you can type either C-u 2 M-@ or M-@ M-@ to mark the next two words. These commands also extend the region in Transient Mark mode, regardless of the last command.

Other commands set both point and mark, to delimit an object in the buffer. For example, M-h (mark-paragraph) moves point to the beginning of the paragraph that surrounds or follows point, and puts the mark at the end of that paragraph (see section 30.3 Paragraphs). It prepares the region so you can indent, case-convert, or kill a whole paragraph. With a prefix argument, if the argument's value is positive, M-h marks that many paragraphs starting with the one surrounding point. If the prefix argument is -n, M-h also marks n paragraphs, running back form the one surrounding point. In that last case, point moves forward to the end of that paragraph, and the mark goes at the start of the region. Repeating the M-h command extends the region to subsequent paragraphs.

C-M-h (mark-defun) similarly puts point before, and the mark after, the current (or following) major top-level definition, or defun (see section 31.2.2 Moving by Defuns). Repeating C-M-h extends the region to subsequent defuns.

C-x C-p (mark-page) puts point before the current page, and mark at the end (see section 30.4 Pages). The mark goes after the terminating page delimiter (to include it in the region), while point goes after the preceding page delimiter (to exclude it). A numeric argument specifies a later page (if positive) or an earlier page (if negative) instead of the current page.

Finally, C-x h (mark-whole-buffer) sets up the entire buffer as the region, by putting point at the beginning and the mark at the end. (In some programs this is called "select all.")

In Transient Mark mode, all of these commands activate the mark.

12.6 The Mark Ring

Aside from delimiting the region, the mark is also useful for remembering a spot that you may want to go back to. To make this feature more useful, each buffer remembers 16 previous locations of the mark, in the mark ring. Commands that set the mark also push the old mark onto this ring. To return to a marked location, use C-u C-SPC (or C-u C-@); this is the command set-mark-command given a numeric argument. It moves point to where the mark was, and restores the mark from the ring of former marks.

If you set set-mark-command-repeat-pop to non-nil, then when you repeat the character C-SPC after typing C-u C-SPC, each repetition moves point to a previous mark position from the ring. The mark positions you move through in this way are not lost; they go to the end of the ring.

Each buffer has its own mark ring. All editing commands use the current buffer's mark ring. In particular, C-u C-SPC always stays in the same buffer.

Many commands that can move long distances, such as M-< (beginning-of-buffer), start by setting the mark and saving the old mark on the mark ring. This is to make it easier for you to move back later. Searches set the mark if they move point. However, in Transient Mark mode, these commands do not set the mark when the mark is already active. You can tell when a command sets the mark because it displays `Mark set' in the echo area.

If you want to move back to the same place over and over, the mark ring may not be convenient enough. If so, you can record the position in a register for later retrieval (see section Saving Positions in Registers).

The variable mark-ring-max specifies the maximum number of entries to keep in the mark ring. If that many entries exist and another one is pushed, the earliest one in the list is discarded. Repeating C-u C-SPC cycles through the positions currently in the ring.

The variable mark-ring holds the mark ring itself, as a list of marker objects, with the most recent first. This variable is local in every buffer.

12.7 The Global Mark Ring

In addition to the ordinary mark ring that belongs to each buffer, Emacs has a single global mark ring. It records a sequence of buffers in which you have recently set the mark, so you can go back to those buffers.

Setting the mark always makes an entry on the current buffer's mark ring. If you have switched buffers since the previous mark setting, the new mark position makes an entry on the global mark ring also. The result is that the global mark ring records a sequence of buffers that you have been in, and, for each buffer, a place where you set the mark.

The command C-x C-SPC (pop-global-mark) jumps to the buffer and position of the latest entry in the global ring. It also rotates the ring, so that successive uses of C-x C-SPC take you to earlier and earlier buffers.

13. Killing and Moving Text

Killing means erasing text and copying it into the kill ring, from which you can bring it back into the buffer by yanking it. (Some systems use the terms "cutting" and "pasting" for these operations.) This is the most common way of moving or copying text within Emacs. Killing and yanking is very safe because Emacs remembers several recent kills, not just the last one. It is versatile, because the many commands for killing syntactic units can also be used for moving those units. But there are other ways of copying text for special purposes.

Most commands which erase text from the buffer save it in the kill ring. These commands are known as kill commands. The commands that erase text but do not save it in the kill ring are known as delete commands. The C-x u (undo) command (see section 21.1 Undo) can undo both kill and delete commands; the importance of the kill ring is that you can also yank the text in a different place or places. Emacs has only one kill ring for all buffers, so you can kill text in one buffer and yank it in another buffer.

The delete commands include C-d (delete-char) and DEL (delete-backward-char), which delete only one character at a time, and those commands that delete only spaces or newlines. Commands that can erase significant amounts of nontrivial data generally do a kill operation instead. The commands' names and individual descriptions use the words `kill' and `delete' to say which kind of operation they perform.