@shorttitlepage GNU Emacs Manual
GNU Emacs Manual
Tenth Edition, Updated for Emacs version 19.28
Richard Stallman Copyright (C) 1985, 1986, 1987, 1993, 1994 Free Software Foundation, Inc.
Tenth Edition
Updated for Emacs Version 19.28,
July 1994
ISBN 1-882114-04-3.
Published by the Free Software Foundation
675 Massachusetts Avenue
Cambridge, MA 02139 USA
Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.
Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the sections entitled "The GNU Manifesto", "Distribution" and "GNU General Public License" are included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the sections entitled "The GNU Manifesto", "Distribution" and "GNU General Public License" may be included in a translation approved by the Free Software Foundation instead of in the original English.
Cover art by Etienne Suvasa.
This manual documents the use and simple customization of the Emacs editor. The reader is not expected to be a programmer; simple customizations do not require programming skill. But the user who is not interested in customizing can ignore the scattered customization hints.
This is primarily a reference manual, but can also be used as a primer. For complete beginners, it is a good idea to start with the on-line, learn-by-doing tutorial, before reading the manual. To run the tutorial, start Emacs and type C-h t. This way you can learn Emacs by using Emacs on a specially designed file which describes commands, tells you when to try them, and then explains the results you see.
On first reading, just skim chapters one and two, which describe the notational conventions of the manual and the general appearance of the Emacs display screen. Note which questions are answered in these chapters, so you can refer back later. After reading chapter four you should practice the commands there. The next few chapters describe fundamental techniques and concepts that are used constantly. You need to understand them thoroughly, experimenting with them if necessary.
Chapters 14 through 18 describe intermediate-level features that are useful for all kinds of editing. Chapter 19 and following chapters describe features that you may or may not want to use; read those chapters when you need them
Read the Trouble chapter if Emacs does not seem to be working properly. It explains how to cope with some common problems (see section Dealing with Emacs Trouble), as well as when and how to report Emacs bugs (see section Reporting Bugs). To find the documentation on a particular command, look in the index. Keys (character commands) and command names have separate indexes. There is also a glossary, with a cross reference for each term.
This manual is available as a printed book and also as an Info file. The Info file is for on-line perusal with the Info program, which will be the principle way of viewing documentation on-line in the GNU system. Both the Info file and the Info program itself are distributed along with GNU Emacs. The Info file and the printed book contain substantially the same text and are generated from the same source files, which are also distributed along with GNU Emacs.
GNU Emacs is a member of the Emacs editor family. There are many Emacs editors, all sharing common principles of organization. For information on the underlying philosophy of Emacs and the lessons learned from its development, write for a copy of AI memo 519a, "Emacs, the Extensible, Customizable Self-Documenting Display Editor", to Publications Department, Artificial Intelligence Lab, 545 Tech Square, Cambridge, MA 02139, USA. At last report they charge $2.25 per copy. Another useful publication is LCS TM-165, "A Cookbook for an Emacs", by Craig Finseth, available from Publications Department, Laboratory for Computer Science, 545 Tech Square, Cambridge, MA 02139, USA. The price today is $3.
This edition of the manual is intended for use with GNU Emacs installed on GNU and Unix systems. GNU Emacs can also be used on VMS and MS-DOS (aka. MS-DOG) systems, but those systems have different file name syntax and do not support all GNU Emacs features. We don't try to describe VMS usage in this manual. See section MS-DOS Issues, for information about using Emacs on MS-DOS.
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 following this section.
The easiest 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 from host `prep.ai.mit.edu' using anonymous login. See the file `/pub/gnu/GETTING.GNU.SOFTWARE' on that host to find out about your options for copying and which files to use.
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, on various magnetic media or on CD-ROM. This is a convenient and reliable way to get a copy; it is also a good way to help fund our work. (The Foundation has always received most of its funds in this way.) An order form is included at the end of manuals printed by the Foundation. It is also included in the file `etc/ORDERS' in the Emacs distribution. For further information, write to
Free Software Foundation 675 Mass Ave Cambridge, MA 02139 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. If you use GNU Emacs at your workplace, 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.
Copyright (C) 1989, 1991 Free Software Foundation, Inc. 675 Mass Ave, Cambridge, MA 02139, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.
When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.
For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.
We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.
Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.
Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.
The precise terms and conditions for copying, distribution and modification follow.
If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.
To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.
one line to give the program's name and an idea of what it does. Copyright (C) 19yy name of author This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
Also add information on how to contact you by electronic and paper mail.
If the program is interactive, make it output a short notice like this when it starts in an interactive mode:
Gnomovision version 69, Copyright (C) 19yy name of author Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details.
The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items--whatever suits your program.
You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision' (which makes passes at compilers) written by James Hacker. signature of Ty Coon, 1 April 1989 Ty Coon, President of Vice
This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License.
You are reading about GNU Emacs, the GNU incarnation of the advanced, self-documenting, customizable, extensible real-time display editor Emacs. (The `G' in `GNU' is not silent.)
We say that Emacs is a display editor because normally the text being edited is visible on the screen and is updated automatically as you type your commands. See section The Organization of the Screen.
We call it a real-time editor because the display is updated very frequently, usually after each character or pair of characters you type. This minimizes the amount of information you must keep in your head as you edit. See section Basic Editing Commands.
We call Emacs advanced because it provides facilities that go beyond simple insertion and deletion: controlling subprocesses; automatic indentation of programs; viewing two or more files at once; and dealing in terms of characters, words, lines, sentences, paragraphs, and pages, as well as expressions and comments in several different 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 Help.
Customizable means that you can change the definitions of Emacs commands in little 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 Manipulating Comments). Another sort of customization is rearrangement of the command set. For example, if you prefer the four basic cursor motion commands (up, down, left and right) on keys in a diamond pattern on the keyboard, you can rebind the keys that way. See section 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 already; the few exceptions could have been written in Lisp but are written in C for efficiency. Although only a programmer can write an extension, anybody can use it afterward.
When run under the X Window System, Emacs provides its own menus and convenient bindings to mouse buttons. But Emacs can provide many of the benefits of a window system on a text-only terminal. For instance, you can look at or edit several files at once, move text between them, and edit files at the same time as you run shell commands.
On a text-only terminal, the Emacs display occupies the whole screen. On the X Window System, Emacs creates its own X windows to use. We use the term frame to mean an entire text-only screen or an entire X 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 under X you can create additional frames if you wish. See section Frames and X Windows.
When you start Emacs, the entire frame except for the last line is devoted to the text you are editing. This area is called window. The last line is a special echo area or minibuffer window where prompts appear and where you can enter responses. You can subdivide the large text window horizontally or vertically into multiple text windows, each of which can be used for a different file (see section Multiple Windows). In this manual, the word "window" always refers to the subdivisions of a frame within Emacs.
The window that the cursor is in is the selected window, in which editing takes place. Most Emacs commands implicitly apply to the text in the selected window (though mouse commands generally operate on whatever window you click them in, whether selected or not). The other windows display text for reference only, unless/until you select them. If you use multiple frames under the X Window System, 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 inverse video if the terminal supports that, and contains text that starts like `-----Emacs: something'. Its purpose is to indicate 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.
Within Emacs, the terminal's 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.
While the cursor appears to point at 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.
Terminals have only one cursor, and when output is in progress it must appear where the typing is being done. This does not mean that point is moving. It is only that Emacs has no way to show you the location of point except when the terminal is idle.
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 where point is in case you display it again later.
When there are multiple windows in a frame, each window has its own point location. The cursor shows the location of point in the selected window. This also is how you can tell which window is selected. If the same buffer appears in more than one window, each window has its own position for point in that buffer.
When there are multiple frames, each frame can display one cursor. The cursor in the selected frame is solid; the cursor in other frames is a hollow box, and appears in the window that would be selected if you give the input focus to that frame.
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'.
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 several purposes.
Echoing means displaying the characters that you type. Outside Emacs, 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 Variables Controlling Display).
If a command cannot be executed, it may print an error message in the echo area. Error messages are accompanied by a beep or by flashing the screen. Also, any input you have typed ahead is thrown away when an error happens.
Some commands print 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 print a message giving you specific information--for example, C-x = prints 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.
The echo area is also used to display the minibuffer, a window that is used for reading 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 The Minibuffer.
Each text window's last line is a mode line which describes what is going on in that window. When there is only one text window, the mode line appears right above the echo area. The mode line is in inverse video if the terminal supports that, it starts and ends with dashes, and it contains text like `Emacs: something'.
A few special editing modes, such as Dired and Rmail, display something else in place of `Emacs: something'. The rest of the mode line still has the usual meaning.
Normally, the mode line looks like this:
--ch-Emacs: buf (major minor)----pos------
This gives information about the buffer being displayed in the window: 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.
buf is the name of the window's buffer. In most cases this is the same as the name of a file you are editing. See section Using Multiple Buffers.
The buffer displayed in the selected window (the window that the cursor is in) is also Emacs's selected buffer, the one that editing takes place in. When we speak of what some command does to "the buffer", we are talking about the currently selected 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.
major is the name of the major mode in effect in the buffer. At any time, each buffer is in one and only one of the possible major modes. The major modes available include Fundamental mode (the least specialized), Text mode, Lisp mode, C mode, Texinfo mode, and many others. See section Major Modes, for details of how the modes differ and how to select one.
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 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 Narrowing. `Def' means that a keyboard macro is being defined. See section Keyboard Macros.
In addition, if Emacs is currently 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 Recursive Editing Levels.
See section Optional Mode Line Features, for features that add other handy information to the mode line, such as the current line number of point, the current time, and whether new mail for you has arrived.
This chapter explains the character sets used by Emacs for input commands and for the contents of files, and also explains the concepts of keys and commands which are fundamental for understanding how Emacs interprets your keyboard and mouse input.
GNU 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 and then pressing a.
Some control characters have special names, and special keys you can type them with: for example, RET, TAB, LFD, DEL and ESC. The space character is usually referred to below as SPC, even though strictly speaking it is a graphic character whose graphic happens to be blank.
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.
But the Emacs character set has room for control variants of all characters, and for distinguishing between C-a and C-A. X Windows makes it possible to enter all these characters. For example, C-- (that's Control-Minus) and C-5 are meaningful Emacs commands under X.
Another Emacs character set extension is that characters have 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 (not the same character as M-a, but those two characters normally have the same meaning in Emacs), M-RET, and M-C-a. For reasons of tradition, we usually write C-M-a rather than M-C-a; logically speaking, the order in which the modifier keys CTRL and META are mentioned does not matter.
Some terminals have a META key, and allow you to type Meta characters by holding this key down. Thus, Meta-a is typed by holding down META and pressing a. The META key works much like the SHIFT key. Such a key is not always labeled META, however, as this function is often a special option for a key with some other primary purpose.
If there is no META key, you can still type Meta characters using two-character sequences starting with ESC. Thus, to enter M-a, you could type ESC a. To enter C-M-a, you would type ESC C-a. ESC is allowed on terminals with Meta keys, too, in case you have formed a habit of using it. X Windows provides 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 X terminals actually provide keys for these modifier flags, and the standard key bindings of Emacs do not include such characters. But you can assign them meanings of your own by customizing Emacs.
Keyboard input includes keyboard keys that are not characters at all: for example function keys and arrow keys. Mouse buttons are also outside the gamut of characters. You can modify these events with the modifier keys CONTROL, META, SUPER, HYPER and ALT like keyboard characters. But these inputs do not have numeric character codes. Instead, Emacs represents them by their names (actually, Lisp objects called symbols).
Input characters and non-character inputs are collectively called input events. See section `Input Events' in The Emacs Lisp Manual, for more information. If you are not doing Lisp programming, but simply want to redefine the meaning of some characters or non-character events, see section 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 recognize these special sequences and converts them to names before any other part of Emacs gets to see them.
A key sequence (key, for short) is a sequence of input events that are meaningful as a unit--as "a single command." Some Emacs command sequences are just one character or one event; for example, just C-f is enough to move forward one character. 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-character 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-character key sequences. There's no limit to the length of a key sequence, but in practice people rarely use sequences longer than four events.
By contrast, you can't add more events onto a complete key. For example, the two-character sequence C-f C-k is not a key, because the C-f is a complete key in itself. It's impossible to give C-f C-k an independent meaning as a command. C-f C-k is two key sequences, not one.
All told, the prefix keys in Emacs are C-c, C-h, C-x, C-x C-a, C-x n, C-x r, C-x v, C-x 4, C-x 5, C-x 6, and ESC. But this is not cast in concrete; it is just a matter of Emacs's standard key bindings. If you customize Emacs, you can make new prefix keys, or eliminate these. See section Customizing Key Bindings.
If you do 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 it too as a prefix). Conversely, if you remove the prefix definition of C-x 4, then C-x 4 f (or C-x 4 anything) is no longer a key.
Typing the help character (C-h) after a prefix character usually displays a list of the commands starting with that prefix. There are a few prefix characters for which this doesn't work--for historical reasons, they have other meanings for C-h which are not easy to change.
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 what makes
the command do what it does. In Emacs Lisp, a command is actually a
special kind of Lisp function; one which specifies how to read arguments
for it and call it interactively. For more information on commands and
functions, see section `What Is a Function' in The Emacs Lisp Reference Manual. (The definition we use in this manual is
simplified slightly.)
The bindings between keys and commands are recorded in various tables called keymaps. See section Keymaps.
When we say that "C-n moves down vertically one line" we are
glossing over a distinction that is irrelevant in ordinary use but is vital
in understanding how to customize Emacs. It is the command
next-line that is programmed to move down vertically. C-n has
this effect because it is bound to that command. If you rebind
C-n to the command forward-word then C-n will move
forward by words instead. Rebinding keys is a common method of
customization.
In the rest of this manual, we usually ignore this subtlety to keep
things simple. To give the information needed for customization, 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 next-line is a command that moves vertically
down and C-n is a key that is standardly bound to it.
While we are on the subject of information for customization only,
it's a good time to 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 remember a value.
Most of the variables documented in this manual exist just to facilitate
customization: some command or other part of Emacs examines the variable
and behaves differently according to the value that you set. Until you
are interested in customizing, you can ignore the information about
variables. When you are ready to be interested, read the basic
information on variables, and then the information on individual
variables will make sense. See section Variables.
Emacs buffers use an 8-bit character set, because bytes have 8 bits. ASCII graphic characters in Emacs buffers are displayed with their graphics. The newline character (which has the same character code as LFD) is displayed by starting a new line. The tab character is displayed by moving to the next tab stop column (normally every 8 columns). Other control characters are displayed as a caret (`^') followed by the non-control version of the character; thus, C-a is displayed as `^A'. Non-ASCII characters 128 and up are displayed with octal escape sequences; thus, character code 243 (octal) is displayed as `\243'.
You can customize the display of these character codes (or ASCII characters) by creating a display table. See section `Display Tables' in The Emacs Lisp Reference Manual. This is useful for editing files that use 8-bit European character sets. See section European Character Set Display.
The usual way to invoke Emacs is with the shell command `emacs'. Emacs clears the screen and then displays an initial help message and copyright notice. Some operating systems discard all type-ahead when Emacs starts up; they give Emacs no way to prevent this. Therefore, it is advisable to wait until Emacs clears the screen before typing your first editing command.
If you run Emacs from a shell window under the X Window System, run it in the background with `emacs&'. This way, Emacs does not tie up the shell window, so you can use that to run other shell commands while Emacs operates its own X windows. You can begin typing Emacs commands as soon as you direct your keyboard input to the Emacs frame.
When Emacs starts up, it makes 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, or you can ignore that capability and simply doodle. (You can
specify a different major mode for this buffer by setting the variable
initial-major-mode in your init file. See section The Init File, `~/.emacs'.)
It is possible to specify files to be visited, Lisp files to be loaded, and functions to be called, by giving Emacs arguments in the shell command line. See section Command Line Arguments. But we don't recommend doing this. The feature exists mainly for compatibility with other editors.
Many other editors are designed to be started afresh each time you want to edit. You edit one file and then exit the editor. The next time you want to edit either another file or the same one, you must run the editor again. With these editors, it makes sense to use a command line argument to say which file to edit.
But starting a new Emacs each time you want to edit a different file does not make sense. For one thing, this would be annoyingly slow. For another, this would fail to take advantage of Emacs's ability to visit more than one file in a single editing session. And it would lose the other accumulated context, such as registers, undo history, and the mark ring.
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 want to edit a different file, you visit it with the existing Emacs, which eventually comes to have many files in it ready for editing. Usually you do not kill the Emacs until you are about to log out. See section File Handling, for more information on visiting more than one file.
There are two commands for exiting Emacs because there are two kinds of exiting: suspending Emacs and killing Emacs.
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, with the same buffers, same kill ring, same undo history, and so on. This is the usual way to exit.
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.
suspend-emacs) or iconify a frame
(iconify-or-deiconify-frame).
save-buffers-kill-emacs).
To suspend Emacs, type C-z (suspend-emacs). This 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 do not support suspending programs, C-z starts an inferior shell that communicates directly with the terminal. 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.) The only way on these systems to get back to the shell from which Emacs was run (to log out, for example) is to kill Emacs.
Suspending also fails if you run Emacs under a shell that doesn't
support suspending programs, 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.
(One might also describe Emacs's parent shell as "inferior" for
failing to support job control properly, but that is a matter of taste.)
When Emacs communicates directly with an X server and creates its own
dedicated X windows, C-z has a different meaning. Suspending an
applications that uses its own X windows is not meaningful or useful.
Instead, C-z runs the command iconify-or-deiconify-frame,
which temporarily closes up the selected Emacs frame. The way to get
back to a shell window is with the window manager.
To kill Emacs, type C-x C-c (save-buffers-kill-emacs). A
two-character key is used for this to make it harder to type. This
command first offers to save any modified file-visiting buffers. If you
do not save them all, it asks for reconfirmation with yes before
killing Emacs, since any changes not saved will be lost forever. Also,
if any subprocesses are still running, C-x C-c asks for
confirmation about them, since killing Emacs will kill the subprocesses
immediately.
There is no way to restart an Emacs session once you have killed it. You can, however, arrange for Emacs to record certain session information, such as which files are visited, when you kill it, so that the next time you restart Emacs it will try to visit the same files and so on. See section 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 Keymaps).
We now give the basics of how to enter text, make corrections, and
save the text in a file. If this material is new to you, you might
learn it more easily by running the Emacs learn-by-doing tutorial. To
use the tutorial, run Emacs and type Control-h t
(help-with-tutorial).
To clear the screen and redisplay, type C-l (recenter).
To insert printing characters into the text you are editing, just type them. This inserts the characters you type into the buffer at the cursor (that is, at point; see section Point). The cursor moves forward, and any text after the cursor moves forward too. If the text in the buffer is `FOOBAR', with the cursor before the `B', then if you type XX, you get `FOOXXBAR', with the cursor still before the `B'.
To delete text you have just inserted, use DEL. DEL deletes the character before the cursor (not the one that the cursor is on top of or under; that is the character after the cursor). The cursor and all characters after it move backwards. Therefore, if you type a printing character and then type DEL, they cancel out.
To end a line and start typing a new one, type RET. This inserts a newline character in the buffer. If point is in the middle of a line, RET splits the line. Typing DEL when the cursor is at the beginning of a line deletes the preceding newline, thus joining the line with the preceding line.
Emacs can split lines automatically when they become too long, if you turn on a special minor mode called Auto Fill mode. See section Filling Text, for how to use Auto Fill mode.
If you prefer to have text characters replace (overwrite) existing text rather than shove it to the right, you can enable Overwrite mode, a minor mode. See section Minor Modes.
Direct insertion works for printing characters and SPC, but other
characters act as editing commands and do not insert themselves. If you
need to insert a control character or a character whose code is above 200
octal, 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:
A numeric argument to C-q specifies how many copies of the quoted character should be inserted (see section 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 was typed to invoke it. Some major modes
rebind DEL to other commands.
To do more than insert characters, you have to know how to move point (see section 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 (these date back to the days before terminals had arrow keys, and are usable on terminals which don't have them). Others do more sophisticated things.
beginning-of-line).
end-of-line).
forward-char).
backward-char).
forward-word).
backward-word).
next-line). This command
attempts to keep the horizontal position unchanged, so if you start in
the middle of one line, you end in the middle of the next. When on
the last line of text, C-n creates a new line and moves onto it.
previous-line).
move-to-window-line). Text does not move on the screen.
A numeric argument says which screen line to place point on. It counts
screen lines down from the top of the window (zero for the top line). A
negative argument counts lines from the bottom (-1 for the bottom
line).
beginning-of-buffer). With
numeric argument n, move to n/10 of the way from the top.
See section Numeric Arguments, for more information on numeric arguments.end-of-buffer).
set-goal-column). Henceforth, those
commands always move to this column in each line moved into, or as
close as possible given the contents of the line. This goal column remains
in effect until canceled.
If you set the variable track-eol to a non-nil value,
then C-n and C-p when at the end of the starting line move
to the end of another line. Normally, track-eol is nil.
See section Variables, for how to set variables such as track-eol.
Normally, C-n on the last line of a buffer appends a newline to
it. If the variable next-line-add-newlines is nil, then
C-n gets an error instead (like C-p on the first line).
delete-backward-char).
delete-char).
kill-line).
kill-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 together that line and the next line.
To erase a larger amount of text, use the C-k key, which 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 and the next line.
See section Deletion and Killing, for more flexible ways of killing text.
You can undo all the recent changes in the buffer text, up to a
certain point. Each buffer records changes individually, and the undo
command always applies to the current buffer. Usually each editing
command makes a separate entry in the undo records, but some commands
such as query-replace make many entries, and very simple commands
such as self-inserting characters are often grouped to make undoing less
tedious.
undo).
The command C-x u or C-_ is how you undo. The first time you give this command, it undoes the last change. Point moves back to where it was before the command that made the change.
Consecutive repetitions of C-_ or C-x u undo earlier and earlier changes, back to the limit of the undo information available. If all recorded changes have already been undone, the undo command prints an error message and does nothing.
Any command other than an undo command breaks the sequence of undo commands. Starting from that moment, the previous undo commands become ordinary changes that you can undo. Thus, to redo changes you have undone, type C-f or any other command that will harmlessly break the sequence of undoing, then type more undo commands.
If you notice that a buffer has been modified accidentally, the easiest way to recover is to type C-_ repeatedly until the stars disappear from the front of the mode line. At this time, all the modifications you made have been canceled. Whenever an undo command makes the stars disappear from the mode line, it means that the buffer contents are the same as they were when the file was last read in or saved.
If you do not remember whether you changed the buffer deliberately, type C-_ once. When you see the last change you made undone, you will see whether it was an intentional change. If it was an accident, leave it undone. If it was deliberate, redo the change as described above.
Not all buffers record undo information. Buffers whose names start with spaces don't; these buffers are used internally by Emacs and its extensions to hold text that users don't normally look at or edit.
You cannot undo mere cursor motion; only changes in the buffer contents save undo information. 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 The Mark Ring).
When the undo information for a buffer becomes too large, Emacs
discards the oldest undo information from time to time (during garbage
collection). You can specify how much undo information to keep by
setting two variables: undo-limit and undo-strong-limit.
Their values are expressed in units of bytes of space.
The variable undo-limit sets a soft limit: Emacs keeps undo
data for enough commands to reach this size, and perhaps exceed it, but
does not keep data for any earlier commands beyond that. Its default
value is 20000. The variable undo-strong-limit sets a stricter
limit: the command which pushes the size past this amount is itself
forgotten. Its default value is 30000.
Regardless of the values of those variables, the most recent change is never discarded, so there is no danger that garbage collection occurring right after an unintentional large change might prevent you from undoing it.
The reason the undo command has two keys, C-x u and
C-_, set up to run it is that it is worthy of a single-character
key, but on some keyboards it is not obvious how to type C-_.
C-x u is an alternative you can type straightforwardly on any
terminal.
The commands described above are sufficient for creating and altering text in an Emacs buffer; the more advanced Emacs commands just make things easier. But 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 look at or use the contents of a file in any way, including editing the file with Emacs, you must specify the file name.
Consider a file named `/usr/rms/foo.c'. In Emacs, to begin editing this file, type
C-x C-f /usr/rms/foo.c 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 The Minibuffer).
Emacs obeys the command by visiting the file: creating a buffer,
copying the contents of the file into the buffer, and then displaying
the buffer for you to edit. If you alter the text, you can save
the new text in the file by typing C-x C-s (save-buffer).
This makes the changes permanent by copying the altered buffer contents
back into the file `/usr/rms/foo.c'. Until you save, the changes
exist only inside Emacs, and the file `foo.c' is unaltered.
To create a file, just visit the file 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. The file is actually created when you save this buffer with C-x C-s.
Of course, there is a lot more to learn about using files. See section File Handling.
If you forget what a key does, you can find out with the Help
character, which is C-h. Type C-h k followed by the key you
want to know about; for example, C-h k C-n tells you all about
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 Help.
Here are special commands and techniques for putting in and taking out blank lines.
open-line).
delete-blank-lines).
When you want to insert a new line of text before an existing line, you
can do it by typing 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 to tell it how many blank lines to make. See section Numeric Arguments, for how. If you have a fill prefix, then C-o command inserts the fill prefix on the new line, when you use it at the beginning of a line. See section 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
solitary blank line deletes that blank line. When point is on a
nonblank line, C-x C-o deletes any blank lines following that
nonblank line.
If you add too many characters to one line without breaking it with RET, the line will grow to occupy two (or more) lines on the screen, with a `\' at the extreme right margin of all but the last of them. The `\' says that the following screen line is not really a distinct line in the text, but just the continuation of a line too long to fit the screen. Continuation is also called line wrapping.
Sometimes it is nice to have Emacs insert newlines automatically when a line gets too long. Continuation on the screen does not do that. Use Auto Fill mode (see section Filling Text) if that's what you want.
As an alternative to continuation, Emacs can display long lines by truncation. This means that all the characters that do not fit in the width of the screen or window do not appear at all. They remain in the buffer, temporarily invisible. `$' is used in the last column instead of `\' to inform you that truncation is in effect.
Truncation instead of continuation happens whenever horizontal
scrolling is in use, and optionally in all side-by-side windows
(see section Multiple Windows). You can enable truncation for a particular buffer by
setting the variable truncate-lines to non-nil in that
buffer. (See section Variables.) Altering the value of
truncate-lines makes it local to the current buffer; until that
time, the default value is in effect. The default is initially
nil. See section Local Variables.
See section Variables Controlling Display, for additional variables that affect how text is displayed.
Here are commands to get information about the size and position of parts of the buffer, and to count lines.
count-lines-region).
what-cursor-position).
There are two commands for printing the current line number. M-x what-line computes the current line number and displays it in the echo area. M-x line-number-mode enables display of the current line number in the mode line; once you turn this on, the number updates as you move point, so it remains valid all the time. See section The Mode Line.
Line numbers count from one at the beginning of the buffer. To go to a given line by number, use M-x goto-line; it prompts you for the line number.
By contrast, M-x what-page counts pages from the beginning of the file, and counts lines within the page, printing both numbers. See section Pages.
While on this subject, we might as well mention M-= (count-lines-region),
which prints the number of lines in the region (see section The Mark and the Region).
See section Pages, for the command C-x l which counts the lines in the
current page.
The command C-x = (what-cursor-position) can be used to find out
the column that the cursor is in, and other miscellaneous information about
point. It prints a line in the echo area that looks like this:
Char: x (0170) point=65986 of 563027(12%) x=44
(In fact, this is the output produced when point is before the `x=44' in the example.)
The two values after `Char:' describe the character that follows point, first by showing it and second by giving its octal character code.
`point=' is followed by the position of point expressed as a character count. The front of the buffer counts as position 1, one character later as 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.
`x=' 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 = prints additional text describing the currently accessible range. For example, it might display this:
Char: x (0170) point=65986 of 563025(12%) <65102 - 68533> x=44
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 Narrowing.
If point is at the end of the buffer (or the end of the accessible part), C-x = omits any description of the character after point. The output looks like this:
point=563026 of 563025(100%) x=0
Any Emacs command can be given 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, the easiest way to specify a numeric argument is to type digits and/or a minus sign while holding down the the META key. For example,
M-5 C-nwould move 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 contribute to an argument for the next command.
Another way of specifying an argument is to use the C-u
(universal-argument) command followed by the digits of the
argument. With C-u, you can type the argument digits without
holding down modifier keys; C-u works on all terminals. To type a
negative argument, type a minus sign after C-u. Just a minus sign
without digits normally means -1.
C-u followed by a character which is neither a digit nor a minus sign has the special meaning of "multiply by four". It multiplies the argument for the next command by four. C-u twice 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 only about whether there is an argument, and not about
its value. For example, the command M-q (fill-paragraph) with
no argument fills text; with an argument, it justifies the text as well.
(See section 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 Deletion and Killing, for more information on
C-k.)
A few commands treat a plain C-u differently from an ordinary argument. A few others may treat an argument of just a minus sign differently from an argument of -1. These unusual cases are described when they come up; they are always for reasons of convenience of use of the individual command.
You can use a numeric argument to insert multiple copies of a character. This is straightforward unless the character is 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, rather than inserting anything. To separate the digit to insert from the argument, type 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 the argument before the command, and to distinguish these arguments from minibuffer arguments that come after the command.
The minibuffer is the facility used by Emacs commands to read arguments more complicated than a single number. Minibuffer arguments can be file names, buffer names, Lisp function names, Emacs command names, Lisp expressions, and many other things, depending on the command reading the argument. 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, and the terminal's cursor moves there. The beginning of the minibuffer line displays a prompt which says what kind of input you should supply and how it will be used. Often this prompt is derived from the name of the command that the argument is for. The prompt normally ends with a colon.
Sometimes a default argument appears in parentheses after the colon; it too is part of the prompt. The default will be used as the argument value if you enter an empty argument (e.g., just type RET). For example, commands that read buffer names always show a default, which is the name of the buffer that will be used if you type just RET.
The simplest way to enter a minibuffer argument is to type the text you want, terminated by RET which exits the minibuffer. You can cancel the command that wants the argument, and get out of the minibuffer, by typing C-g.
Since the minibuffer uses the screen space of the echo area, it can conflict with other ways Emacs customarily uses the echo area. Here is how Emacs handles such conflicts:
Sometimes the minibuffer starts out with text in it. For example, when you are supposed to give a file name, the minibuffer starts out containing the default directory, which ends with a slash. This is to inform you which directory the file will be found in if you do not specify a directory.
For example, the minibuffer might start out with these contents:
Find File: /u2/emacs/src/
where `Find File: ' is the prompt. Typing buffer.c specifies the file `/u2/emacs/src/buffer.c'. To find files in nearby directories, use ..; thus, if you type ../lisp/simple.el, you will get the file named `/u2/emacs/lisp/simple.el'. Alternatively, you can kill with M-DEL the directory names you don't want (see section Words).
If you don't want any of the default, you can kill it with C-a C-k. But you don't need to kill the default; you can simply ignore it. Insert an absolute file name, one starting with a slash or a tilde, after the default directory. For example, to specify the file `/etc/termcap', just insert that name, giving these minibuffer contents:
Find File: /u2/emacs/src//etc/termcap
Two slashes in a row are not normally meaningful in a file name, but they are allowed in GNU Emacs. They mean, "ignore everything before the second slash in the pair." Thus, `/u2/emacs/src/' is ignored in the example above, and you get the file `/etc/termcap'.
If you set insert-default-directory to nil, the default
directory is not inserted in the minibuffer. This way, the minibuffer
starts out empty. But the name you type, if relative, is still
interpreted with respect to the same default directory.
The minibuffer is an Emacs buffer (albeit a peculiar one), and the usual Emacs commands are available for editing the text of an argument you are entering.
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 LFD. (Recall that a newline is really the LFD character.)
The minibuffer has its own window which always has space on the screen but acts as if it were not there when the minibuffer is not in use. When the minibuffer is in use, its window is just like the others; you can switch to another window with C-x o, edit text in other windows and perhaps even visit more files, before returning to the minibuffer to submit the argument. You can kill text in another window, return to the minibuffer window, and then yank the text to use it in the argument. See section Multiple Windows.
There are some restrictions on the use of the minibuffer window, however. You cannot switch buffers in it--the minibuffer and its window are permanently attached. Also, you cannot split or kill the minibuffer window. But you can make it taller in the normal fashion with C-x ^. If you enable Resize-Minibuffer mode, then the minibuffer window expands vertically as necessary to hold the text that you put in the minibuffer. Use M-x resize-minibuffer-mode to enable or disable this minor mode (see section Minor Modes).
If while in the minibuffer you issue a command that displays help text of any sort in another window, you can use the C-M-v command while in the minibuffer to scroll the help text. This lasts until you exit the minibuffer. This feature is especially useful if a completing minibuffer gives you a list of possible completions. See section Using Other Windows.
Emacs normally disallows most commands that use the minibuffer while
the minibuffer is selected. This rule is to prevent recursive
minibuffers from confusing novice users. If you want to be able to use
such commands in the minibuffer, set the variable
enable-recursive-minibuffers to a non-nil value.
For certain kinds of arguments, you can use completion to enter the argument value. Completion means that you type part of the argument, then Emacs visibly fills in the rest, or as much as can be determined from the part you have typed.
When completion is available, certain keys---TAB, RET, and SPC---are rebound to complete the text present in the minibuffer into a longer string that it stands for, by matching it against a set of completion alternatives provided by the command reading the argument. ? is defined to display a list of possible completions of what you have inserted.
For example, when M-x uses the minibuffer to read the name of a command, it provides a list of all available Emacs command names to complete against. The completion keys match the text in the minibuffer against all the command names, find any additional name characters implied by the ones already present in the minibuffer, and add those characters to the ones you have given. This is what makes it possible to type M-x ins SPC b RET instead of M-x insert-buffer RET (for example).
Case is normally significant in completion, because it is significant in most of the names that you can complete (buffer names, file names and command names). Thus, `fo' does not complete to `Foo'. Completion does ignore case distinctions for certain arguments in which case does not matter.
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 only two: auto-fill-mode and
auto-save-mode. These are the same as far as auto-, so the
`au' in the minibuffer changes to `auto-'.
If you type TAB again immediately, there are multiple possibilities for the very next character--it could be `s' or `f'---so no more characters are added; instead, TAB displays a list of all possible completions in another window.
If you go on to type f TAB, this TAB sees
`auto-f'. The only command name starting this way is
auto-fill-mode, so completion fills in the rest of that. You now
have `auto-fill-mode' in the minibuffer after typing just au
TAB f TAB. Note that TAB has this effect because in
the minibuffer it is bound to the command minibuffer-complete
when completion is available.
Here is a list of the completion commands defined in the minibuffer when completion is available.
minibuffer-complete).
minibuffer-complete-word).
minibuffer-complete-and-exit).
minibuffer-list-completions).
SPC completes much like TAB, but never goes beyond 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 stops completing after `fill-'. This gives
`auto-fill-'. Another SPC at this point completes all the
way to `auto-fill-mode'. SPC in the minibuffer when
completion is available runs the command
minibuffer-complete-word.
Here are some commands you can use to choose a completion from a window that displays a list of completions:
mouse-choose-completion).
You use this command while you are in the minibuffer; but you must click
in the list of completions, not in the minibuffer itself.
choose-completion). To
use this command, you must first switch windows to the window that shows
the list of completions.
There are three different ways that RET can work in completing minibuffers, depending on how the argument will be used.
The completion commands display a list of all possible completions in a window whenever there is more than one possibility for the very next character. Also, typing ? explicitly requests such a list. If the list of completions is long, you can scroll it with C-M-v (see section Using Other Windows).
When completion is done on file names, certain file names are usually
ignored. The variable completion-ignored-extensions contains a
list of strings; a file whose name ends in any of those strings is
ignored as a possible completion. 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. Ignored extensions do not apply to
lists of completions--those always mention all possible completions.
Normally, a completion command that finds the next character is undetermined
automatically displays a list of all possible completions. If the variable
completion-auto-help is set to nil, this does not happen,
and you must type ? to display the possible completions.
The complete library implements a more powerful kind of
completion that can complete multiple words at a time. For example, it
can complete the command name abbreviation p-b into
print-buffer, because no other command starts with two words
whose initials are `p' and `b'. To use this library, put
(load "complete") in your `~/.emacs' file (see section The Init File, `~/.emacs').
The icomplete library does not change what completion does, but
it presents a constantly updated display that tells you what completions
are available. To use this library, put (load "icomplete") in
your `~/.emacs' file.
Every argument that you enter with the minibuffer is saved on a minibuffer history list so that you can use it again later in another argument. Special commands load the text of an earlier argument in the minibuffer. They discard the old minibuffer contents, so you can think of them as moving through the history of previous arguments.
previous-history-element).
next-history-element).
previous-matching-history-element).
next-matching-history-element).
The simplest way to reuse the saved arguments in the history list is
to move through the history list one element at a time. While in the
minibuffer, type M-p (previous-history-element) to "move
to" the next earlier minibuffer input, and use M-n
(next-history-element) to "move to" the next later input.
The previous input that you fetch from the history entirely replaces the contents of the minibuffer. To use it as the argument, exit the minibuffer as usual with 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.
There are also commands to search forward or backward through the
history. As of this writing, they search for history elements that
match a regular expression that you specify with the minibuffer.
M-r (previous-matching-history-element) searches older
elements in the history, while M-s
(next-matching-history-element) searches newer elements. By
special dispensation, these commands can use the minibuffer to read
their arguments even though you are already in the minibuffer when you
issue them.
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. There is a list for arguments of commands like
query-replace. There are several very specific history lists,
including one for command names read by M-x and one for
compilation commands read by compile. Finally, there is one
"miscellaneous" history list that most minibuffer arguments use.
Every command that uses the minibuffer at least once is recorded on a special history list, 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.
repeat-complex-command).
C-x ESC ESC is used to re-execute a recent minibuffer-using command. With no argument, it repeats the last such command. A numeric argument specifies which command to repeat; one means the last one, and larger numbers specify earlier ones.
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. If you type just RET, the command is repeated as before. You can also change the command by editing the Lisp expression. Whatever expression you finally submit is what will be executed. The repeated command is added to the front of the command history unless it is identical to the most recently executed command already there.
Even if you don't understand Lisp syntax, it will probably be obvious which command is displayed for repetition. If you do not change the text, it will repeat exactly as before.
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 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 resubmit it by typing RET as usual.
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 reexecute a command by calling eval with the
command-history element.
The Emacs commands that are used often or that must be quick to type are bound to keys--short sequences of characters--for convenient use. Other Emacs commands that do not need to be brief are not bound to keys; to run them, you must refer to them by name.
A command name is, by convention, made up of one or more words,
separated by hyphens; for example, auto-fill-mode or
manual-entry. The use of English words makes the command name
easier to remember than a key made up of obscure characters, even though
it is more characters to type.
The way to run a command by name is to start with M-x, type the command name, and finish it with RET. M-x uses the minibuffer to read the command name. RET exits the minibuffer and runs the command. The string `M-x' appears at the beginning of the minibuffer as a prompt to remind you to enter the name of a command to be run. See section The Minibuffer, for full information on the features of the minibuffer.
You can use completion to enter the command name. For example, the
command forward-char can be invoked by name by typing
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. You can run any Emacs command by name using
M-x, whether or not any keys are bound to it.
If you type C-g while the command name is being read, you cancel the M-x command and get out of the minibuffer, ending up at top level.
To pass a numeric argument to the command you are invoking with M-x, specify the numeric argument before the M-x. M-x passes the argument along to the command it runs. The argument value appears in the prompt while the command name is being read.
Normally, when describing a command that is run by name, we omit the RET that is needed to terminate the name. Thus we might speak of M-x auto-fill-mode rather than M-x auto-fill-mode RET. We mention the RET only when there is a need to emphasize its presence, such as when we show the command together with following arguments.
M-x works by running the command
execute-extended-command, which is responsible for reading the
name of another command and invoking it.
Emacs provides extensive help features accessible through a single character, C-h. C-h is a prefix key that is used only for documentation-printing commands. The characters that you can type after C-h are called help options. One help option is C-h; that is how you ask for help about using C-h. To cancel, type C-g.
C-h C-h displays a list of the possible help options, each with a brief description. Before you type a help option, you can use SPC or DEL to scroll through the list.
C-h means "help" in various other contexts as well. For
example, in query-replace, it describes the options available.
After a prefix key, it displays a list of the alternatives that can
follow the prefix key. (A few prefix keys don't support this because
they define other meanings for C-h.)
Here is a summary of the defined help commands.
command-apropos).
describe-bindings).
describe-key-briefly). Here c stands for `character'. For more
extensive information on key, use C-h k.
describe-function). Since commands are Lisp functions,
a command name may be used.
info).
The complete Emacs manual is available on-line in Info.
describe-key).
view-lossage).
describe-mode).
view-emacs-news).
finder-by-keyword).
describe-syntax). See section The Syntax Table.
help-with-tutorial).
describe-variable).
where-is).
info-goto-emacs-command-node).
info-goto-emacs-key-command-node).
The most basic C-h options are C-h c
(describe-key-briefly) and C-h k (describe-key).
C-h c key prints in the echo area the name of the command
that key is bound to. For example, C-h c C-f prints
`forward-char'. Since command names are chosen to describe what
the commands do, this is a good way to get 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. This is too big for the echo area, so a window is used for the display.
C-h c and C-h k work for any sort of key sequences, including function keys and mouse events.
C-h f (describe-function) reads the name of a Lisp function
using the minibuffer, then displays that function's documentation string
in a window. Since commands are Lisp functions, you can use this to get
the documentation of a command that you know by name. 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 are planning to
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 abbreviations that work in
M-x don't work in C-h f. An abbreviation may be unique
among command names yet fail to be unique when other function names are
allowed.
The function name for C-h f to describe has a default which is
used if you type RET leaving the minibuffer empty. The default is
the function called by the innermost Lisp expression in the buffer around
point, provided that is a valid, defined Lisp function name. 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 the default is to describe the function
make-vector.
C-h f is often useful just to verify that you have the right spelling for the function name. If C-h f mentions a default in the prompt, you have typed the name of a defined Lisp function. If that is all you want to know, just type C-g to cancel the C-h f command, then go on editing.
C-h w command RET tells you what keys are bound to
command. It prints a list of the keys in the echo area. If it
says the command is not on any key, you must use M-x to run it.
C-h w runs the command where-is.
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, but only if that is the name of a known Lisp
variable. See section Variables.
A more sophisticated sort of question to ask is, "What are the
commands for working with files?" To ask this question, type C-h
a file RET, which displays a list of all command names that
contain `file', including copy-file, find-file, and
so on. With each command name appears a brief description of how to use
the command, and what keys you can currently invoke it with. For
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 command-apropos.
Because C-h a looks only for functions whose names contain the string which you specify, you must use ingenuity in choosing the string. If you are looking for commands for killing backwards and C-h a kill-backwards RET doesn't reveal any, don't give up. Try just kill, or just backwards, or just back. Be persistent. Also note that you can use a regular expression as the argument, for more flexibility (see section Syntax of Regular Expressions).
Here is a set of arguments to give to C-h a that covers many
classes of Emacs commands, since there are strong conventions for naming
the standard Emacs commands. By giving you a feel for the naming
conventions, this set should also serve to aid you in developing a
technique for picking apropos strings.
char, line, word, sentence, paragraph, region, page, sexp, list, defun, rect, buffer, frame, window, 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.
To list all Lisp symbols that contain a match for a regexp, not just the ones that are defined as commands, use the command M-x apropos instead of C-h a. This command does not check key bindings by default; specify a numeric argument if you want it to check them.
The super-apropos command is like apropos except that it
searches documentation strings as well as symbol names for matches for
the specified regular expression.
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:
bib.
C-h i (info) runs the Info program, which is used for
browsing through structured documentation files. The entire Emacs manual
is available within Info. Eventually all the documentation of the GNU
system will be available. Type h after entering Info to run
a tutorial on using Info.
There are two special help commands for accessing Emacs documentation
through Info. C-h C-f function RET enters Info and
goes straight to the documentation of the Emacs function
function. C-h C-k key enters Info and goes straight
to the documentation of the key key. These two keys run the
commands Info-goto-emacs-command-node and
Info-goto-emacs-key-command-node.
If something surprising happens, and you are not sure what commands you
typed, use C-h l (view-lossage). C-h l prints the last
100 command characters you typed in. If you see commands that you don't
know, you can use C-h c to find out what they do.
Emacs has numerous major modes, each of which redefines a few keys and
makes a few other changes in how editing works. C-h m
(describe-mode) prints documentation on the current major mode,
which normally describes all the commands that are changed in this
mode.
C-h b (describe-bindings) and C-h s
(describe-syntax) present other information about the current
Emacs mode. C-h b displays a list of all the key bindings now in
effect; the local bindings defined by the current minor modes first,
then the local bindings defined by the current major mode, and finally
the global bindings (see section Customizing Key Bindings). C-h s displays the
contents of the syntax table, with explanations of each character's
syntax (see section The Syntax Table).
You can get a similar list 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.)
The other C-h options display various files of useful
information. C-h C-w displays the full details on the complete
absence of warranty for GNU Emacs. C-h n (view-emacs-news)
displays the file `emacs/etc/NEWS', which contains documentation on
Emacs changes arranged chronologically. C-h t
(help-with-tutorial) displays the learn-by-doing Emacs tutorial.
C-h C-c (describe-copying) displays the file
`emacs/etc/COPYING', which tells you the conditions you must obey
in distributing copies of Emacs. C-h C-d
(describe-distribution) displays the file
`emacs/etc/DISTRIB', which tells you how you can order a copy of
the latest version of Emacs. C-h C-p (describe-project)
displays general information about the GNU Project.
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. You can move point or the mark to adjust the boundaries of the region. It doesn't matter which one is set first chronologically, or which one comes earlier in the text.
Once the mark has been set, it remains where you put it until it is set again at another place. The mark remains fixed with respect to the preceding character if text is inserted or deleted in the buffer. Each Emacs buffer has its own mark, so that when you return to a buffer that had been selected previously, it has the same mark it had before.
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 contains 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.
Here are some commands for setting the mark:
set-mark-command).
exchange-point-and-mark).
mouse-save-then-kill).
For example, suppose you wish to convert part of the buffer to all
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 simply sets the mark, leaving point unchanged. Both of these methods copy the region into the kill ring in addition to setting the mark; that gives behavior consistent with other window-driven applications, but if you don't want to modify the kill ring, you must use keyboard commands to set the mark. See section Mouse Commands.
Ordinary terminals have only one cursor, so there is no way for Emacs
to show you where the mark is located. You have to remember. 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
reactivates the mark.
C-x C-x is also useful when you are satisfied with the position of point but want to move the mark; do C-x C-x to put point at that end of the region, and then move it. A second use of C-x C-x, if necessary, puts the mark at the new position with point back at its original position.
There is no such character as C-SPC in ASCII; when you
type SPC while holding down CTRL, what you get on most
ordinary terminals is the character C-@. This key is actually
bound to set-mark-command. But unless you are unlucky enough to
have a terminal where typing C-SPC does not produce
C-@, you might as well think of this character as
C-SPC. Under X, C-SPC is actually a distinct
character, but its binding is still set-mark-command.
Many Emacs commands move the mark and invisibly set new regions. This means that there is almost always some region that you can act on. This is convenient, provided you get used to keeping track of the mark's position.
Some people prefer a more rigid mode of operation in which you must set up a region for each command that uses one--in which the region "lasts" only temporarily. This is called Transient Mark mode. It is particularly well-suited to window systems such as X, since Emacs can highlight the region when it is active.
To enable Transient Mark mode, type M-x transient-mark-mode. This command toggles the mode, so you can repeat the command to turn off the mode.
Here are the details of Transient Mark mode:
set-mark-command).
This makes the mark active; as you move point, you will see the region
highlighting change in extent.
exchange-point-and-mark).
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.
When multiple windows show the same buffer, they can have different regions, because they can have different values of point (though they all share common one mark position). In Transient Mark mode, each window highlights its own region. The part that is highlighted in the selected window is the region that editing commands use. See section Multiple Windows.
Once you have a region and the mark is active, here are some of the ways you can operate on the region:
Most commands that operate on the text in the
region have the word region in their names.
Here are the commands for placing point and the mark around a textual object such as a word, list, paragraph or page.
mark-word). This command and
the following one do not move point.
mark-sexp).
mark-paragraph).
mark-defun).
mark-whole-buffer).
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 Lisp
expression. These commands handle arguments just like M-f and
C-M-f.
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 Paragraphs). It prepares
the region so you can indent, case-convert, or kill a whole paragraph.
C-M-h (mark-defun) similarly puts point before and the
mark after the current or following defun (see section Defuns). C-x
C-p (mark-page) puts point before the current page, and mark at
the end (see section Pages). The mark goes after the terminating page
delimiter (to include it), 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 Transient Mark mode, all of these commands activate the mark.
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. Thus, repeated use of this command moves point to all of the old
marks on the ring, one by one. 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. 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 last one in the list is discarded. Repeating
C-u C-SPC circulates through the positions currently in the
ring.
The variable mark-ring holds the mark ring itself, as a list of
marker objects in the order most recent first. This variable is local
in every buffer.
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.
Killing means erasing text and copying it into the kill ring, from which it can be retrieved by yanking it. Some systems use the terms "cutting" and "pasting" for these operations.
The commonest way of moving or copying text within Emacs is to kill it and later yank elsewhere it in one or more places. This 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.
Emacs has only one kill ring for all buffers, so you can kill text in one buffer and yank it in another buffer.
Most commands which erase text from the buffer save it in the kill
ring so that you can move or copy it to other parts of the buffer.
These commands are known as kill commands. The rest of the
commands that erase text do not save it in the kill ring; they are known
as delete commands. (This distinction is made only for erasure of
text in the buffer.) If you do a kill or delete command by mistake, you
can use the C-x u (undo) command to undo it
(see section Undoing Changes).
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 destroy significant amounts of nontrivial data generally kill.
The commands' names and individual descriptions use the words `kill'
and `delete' to say which they do.
delete-char).
delete-backward-char).
delete-horizontal-space).
just-one-space).
delete-blank-lines).
delete-indentation).
The most basic delete commands are C-d (delete-char) and
DEL (delete-backward-char). C-d deletes the
character after point, the one the cursor is "on top of". This
doesn't move point. DEL deletes the character before the cursor,
and moves point back. You can delete newlines like any other characters
in the buffer; deleting a newline joins two lines. Actually, C-d
and DEL aren't always delete commands; when given arguments, they
kill instead, since they can erase more than one character this way.
The other delete commands are those which delete only whitespace
characters: spaces, tabs and newlines. M-\
(delete-horizontal-space) deletes all the spaces and tab
characters before and after point. M-SPC
(just-one-space) does likewise but leaves a single space after
point, regardless of the number of spaces that existed previously (even
zero).
C-x C-o (delete-blank-lines) deletes all blank lines
after the current line. If the current line is blank, it deletes all
blank lines preceding the current line as well (leaving one blank line,
the current line).
M-^ (delete-indentation) joins the current line and the
previous line, by deleting a newline and all surrounding spaces, usually
leaving a single space. See section Indentation.
kill-line).
The simplest kill command is C-k. If given at the beginning of a line, it kills all the text on the line, leaving it blank. When used on a blank line, it kills the whole line including its newline. To kill an entire non-blank line, go to the beginning and type C-k twice.
More generally, C-k kills from point up to the end of the line, unless it is at the end of a line. In that case it kills the newline following point, thus merging the next line into the current one. Spaces and tabs that you can't see at the end of the line are ignored when deciding which case applies, so if point appears to be at the end of the line, you can be sure C-k will kill the newline.
When C-k is given a positive argument, it kills that many lines and the newlines that follow them (however, text on the current line before point is spared). With a negative argument -n, it kills n lines preceding the current line (together with the text on the current line before point). Thus, C-u - 2 C-k at the front of a line kills the two previous lines.
C-k with an argument of zero kills the text before point on the current line.
If the variable kill-whole-line is non-nil, C-k at
the very beginning of a line kills the entire line including the
following newline. This variable is normally nil.
kill-region).
kill-word). See section Words.
backward-kill-word).
backward-kill-sentence).
See section Sentences.
kill-sentence).
kill-sexp). See section Lists and Sexps.
zap-to-char).
A kill command which is very general is C-w
(kill-region), which kills everything between point and the
mark. With this command, you can kill any contiguous sequence of
characters, if you first set the region around them.
A convenient way of killing is combined with searching: M-z
(zap-to-char) reads a character and kills from point up to (and
including) the next occurrence of that character in the buffer. A
numeric argument acts as a repeat count. A negative argument means to
search backward and kill text before point.
Other syntactic units can be killed: words, with M-DEL and M-d (see section Words); sexps, with C-M-k (see section Lists and Sexps); and sentences, with C-x DEL and M-k (see section Sentences).
You can use kill commands in read-only buffers. They don't actually change the buffer, and they beep to warn you of that, but they do copy the text you tried to kill into the kill ring, so you can yank it into other buffers. Most of the kill commands move point across the text they copy in this way, so that successive kill commands build up a single kill ring entry as usual.
Yanking means reinserting text previously killed. This is what some systems call "pasting". The usual way to move or copy text is to kill it and then yank it elsewhere one or more times.
yank).
yank-pop).
kill-ring-save).
append-next-kill).
All killed text is recorded in the kill ring, a list of blocks of text that have been killed. There is only one kill ring, shared by all buffers, so you can kill text in one buffer and yank it in another buffer. This is the usual way to move text from one file to another. (See section Accumulating Text, for some other ways.)
The command C-y (yank) reinserts the text of the most recent
kill. It leaves the cursor at the end of the text. It sets the mark at
the beginning of the text. See section The Mark and the Region.
C-u C-y leaves the cursor in front of the text, and sets the mark after it. This happens only if the argument is specified with just a C-u, precisely. Any other sort of argument, including C-u and digits, specifies an earlier kill to yank (see section Yanking Earlier Kills).
To copy a block of text, you can use M-w
(kill-ring-save), which copies the region into the kill ring
without removing it from the buffer. This is approximately equivalent
to C-w followed by C-x u, except that M-w does not
alter the undo history and does not temporarily change the screen.
Normally, each kill command pushes a new entry onto the kill ring. However, two or more kill commands in a row combine their text into a single entry, so that a single C-y yanks all the text as a unit, just as it was before it was killed.
Thus, if you want to yank text as a unit, you need not kill all of it with one command; you can keep killing line after line, or word after word, until you have killed it all, and you can still get it all back at once.
Commands that kill forward from point add onto the end of the previous killed text. Commands that kill backward from point add text onto the beginning. This way, any sequence of mixed forward and backward kill commands puts all the killed text into one entry without rearrangement. Numeric arguments do not break the sequence of appending kills. For example, suppose the buffer contains this text:
This is a line -!-of sample text.
with point shown by -!-. If you type M-d M-DEL M-d M-DEL, killing alternately forward and backward, you end up with `a line of sample' as one entry in the kill ring, and `This is text.' in the buffer. (Note the double space, which you can clean up with M-SPC or M-q.)
Another way to kill the same text is to move back two words with M-b M-b, then kill all four words forward with C-u M-d. This produces exactly the same results in the buffer and in the kill ring. M-f M-f C-u M-DEL kills the same text, all going backward; once again, the result is the same. The text in the kill ring entry always has the same order that it had in the buffer before you killed it.
If a kill command is separated from the last kill command by other
commands (not just numeric arguments), it starts a new entry on the kill
ring. But you can force it to append by first typing the command
C-M-w (append-next-kill) right before it. The C-M-w
tells the following command, if it is a kill command, to append the text
it kills to the last killed text, instead of starting a new entry. With
C-M-w, you can kill several separated pieces of text and
accumulate them to be yanked back in one place.
To recover killed text that is no longer the most recent kill, use the
M-y command (yank-pop). It takes the text previously
yanked and replaces it with the text from an earlier kill. So, to
recover the text of the next-to-the-last kill, first use C-y to
yank the last kill, and then use M-y to replace it with the
previous kill. M-y is allowed only after a C-y or another
M-y.
You can understand M-y in terms of a "last yank" pointer which points at an entry in the kill ring. Each time you kill, the "last yank" pointer moves to the newly made entry at the front of the ring. C-y yanks the entry which the "last yank" pointer points to. M-y moves the "last yank" pointer to a different entry, and the text in the buffer changes to match. Enough M-y commands can move the pointer to any entry in the ring, so you can get any entry into the buffer. Eventually the pointer reaches the end of the ring; the next M-y moves it to the first entry again.
M-y moves the "last yank" pointer around the ring, but it does not change the order of the entries in the ring, which always runs from the most recent kill at the front to the oldest one still remembered.
M-y can take a numeric argument, which tells it how many entries to advance the "last yank" pointer by. A negative argument moves the pointer toward the front of the ring; from the front of the ring, it moves "around" to the last entry and continues forward from there.
Once the text you are looking for is brought into the buffer, you can stop doing M-y commands and it will stay there. It's just a copy of the kill ring entry, so editing it in the buffer does not change what's in the ring. As long as no new killing is done, the "last yank" pointer remains at the same place in the kill ring, so repeating C-y will yank another copy of the same previous kill.
If you know how many M-y commands it would take to find the text you want, you can yank that text in one step using C-y with a numeric argument. C-y with an argument restores the text the specified number of entries back in the kill ring. Thus, C-u 2 C-y gets the next to the last block of killed text. It is equivalent to C-y M-y. C-y with a numeric argument starts counting from the "last yank" pointer, and sets the "last yank" pointer to the entry that it yanks.
The length of the kill ring is controlled by the variable
kill-ring-max; no more than that many blocks of killed text are
saved.
The actual contents of the kill ring are stored in a variable named
kill-ring; you can view the entire contents of the kill ring with
the command C-h v kill-ring.
Usually we copy or move text by killing it and yanking it, but there are other methods convenient for copying one block of text in many places, or for copying many scattered blocks of text into one place. To copy one block to many places, store it in a register (see section Registers). Here we describe the commands to accumulate scattered pieces of text into a buffer or into a file.
To accumulate text into a buffer, use M-x append-to-buffer.
This reads a buffer name, them inserts a copy of the region into the
buffer specified. If you specify a nonexistent buffer,
append-to-buffer creates the buffer. The text is inserted
wherever point is in that buffer. If you have been using the buffer for
editing, the copied text goes into the middle of the text of the buffer,
wherever point happens to be in it.
Point in that buffer is left at the end of the copied text, so
successive uses of append-to-buffer accumulate the text in the
specified buffer in the same order as they were copied. Strictly
speaking, append-to-buffer does not always append to the text
already in the buffer--only if point in that buffer is at the end.
However, if append-to-buffer is the only command you use to alter
a buffer, then point is always at the end.
M-x prepend-to-buffer is just like append-to-buffer
except that point in the other buffer is left before the copied text, so
successive prependings add text in reverse order. M-x
copy-to-buffer is similar except that any existing text in the other
buffer is deleted, so the buffer is left containing just the text newly
copied into it.
To retrieve the accumulated text from another buffer, use M-x insert-buffer; this too takes buffername as an argument. It inserts a copy of the text in buffer buffername into the selected buffer. You can alternatively select the other buffer for editing, then optionally move text from it by killing. See section Using Multiple Buffers, for background information on buffers.
Instead of accumulating text within Emacs, in a buffer, you can append text directly into a file with M-x append-to-file, which takes filename as an argument. It adds the text of the region to the end of the specified file. The file is changed immediately on disk.
You should use append-to-file only with files that are
not being visited in Emacs. Using it on a file that you are
editing in Emacs would change the file behind Emacs's back, which
can lead to losing some of your editing.
The rectangle commands operate on rectangular areas of the text: all the characters between a certain pair of columns, in a certain range of lines. Commands are provided to kill rectangles, yank killed rectangles, clear them out, fill them with blanks or text, or delete them. Rectangle commands are useful with text in multicolumn formats, and for changing text into or out of such formats.
When you must specify a rectangle for a command to work on, you do it by putting the mark at one corner and point at the opposite corner. The rectangle thus specified is called the region-rectangle because you control it in about the same way the region is controlled. But remember that a given combination of point and mark values can be interpreted either as a region or as a rectangle, depending on the command that uses them.
If point and the mark are in the same column, the rectangle they delimit is empty. If they are in the same line, the rectangle is one line high. This asymmetry between lines and columns comes about because point (and likewise the mark) is between two columns, but within a line.
kill-rectangle).
delete-rectangle).
yank-rectangle).
open-rectangle). This pushes the previous contents of the
region-rectangle rightward.
The rectangle operations fall into two classes: commands deleting and inserting rectangles, and commands for blank rectangles.
There are two ways to get rid of the text in a rectangle: you can
discard the text (delete it) or save it as the "last killed"
rectangle. The commands for these two ways are C-x r d
(delete-rectangle) and C-x r k (kill-rectangle). In
either case, the portion of each line that falls inside the rectangle's
boundaries is deleted, causing following text (if any) on the line to
move left into the gap.
Note that "killing" a rectangle is not killing in the usual sense; the rectangle is not stored in the kill ring, but in a special place that can only record the most recent rectangle killed. This is because yanking a rectangle is so different from yanking linear text that different yank commands have to be used and yank-popping is hard to make sense of.
To yank the last killed rectangle, type C-x r y
(yank-rectangle). Yanking a rectangle is the opposite of killing
one. Point specifies where to put the rectangle's upper left corner.
The rectangle's first line is inserted there, the rectangle's second
line is inserted at a position one line vertically down, and so on. The
number of lines affected is determined by the height of the saved
rectangle.
You can convert single-column lists into double-column lists using rectangle killing and yanking; kill the second half of the list as a rectangle and then yank it beside the first line of the list. See section Two-Column Editing, for another way to edit multi-column text.
You can also copy rectangles into and out of registers with C-x r r r and C-x r i r. See section Saving Rectangles in Registers.
There are two commands for making with blank rectangles: M-x
clear-rectangle to blank out existing text, and C-x r o
(open-rectangle) to insert a blank rectangle. Clearing a
rectangle is equivalent to deleting it and then inserting a blank
rectangle of the same size.
The command M-x string-rectangle is similar to C-x r o, but it inserts a specified string instead of blanks. You specify the string with the minibuffer. Since the length of the string specifies how many columns to insert, the width of the region-rectangle does not matter for this command. What does matter is the position of the left edge (which specifies the column position for the insertion in each line) and the range of lines that the rectangle occupies. The previous contents of the text beyond the insertion column are pushed rightward.
Emacs registers are places you can save text or positions for later use. Once you save text or a rectangle in a register, you can copy it into the buffer once or many times; you can move point to a position saved in a register once or many times.
Each register has a name which is a single character. A register can store a piece of text, a rectangle, a position, a window configuration, or a file name, but only one thing at any given time. Whatever you store in a register remains there until you store something else in that register. To see what a register r contains, use M-x view-register.
Saving a position records a place in a buffer so that you can move back there later. Moving to a saved position switches to that buffer and moves point to that place in it.
point-to-register).
jump-to-register).
To save the current position of point in a register, choose a name r and type C-x r SPC r. The register r retains the position thus saved until you store something else in that register.
The command C-x r j r moves point to the position recorded in register r. The register is not affected; it continues to record the same position. You can jump to the saved position any number of times.
When you want to insert a copy of the same piece of text several times, it may be inconvenient to yank it from the kill ring, since each subsequent kill moves that entry further down the ring. An alternative is to store the text in a register and later retrieve it.
copy-to-register).
insert-register).
C-x r s r stores a copy of the text of the region into the register named r. Given a numeric argument, C-x r s r deletes the text from the buffer as well.
C-x r i r inserts in the buffer the text from register r. Normally it leaves point before the text and places the mark after, but with a numeric argument (C-u) it puts point after the text and the mark before.
A register can contain a rectangle instead of linear text. The rectangle is represented as a list of strings. See section Rectangles, for basic information on how to specify a rectangle in the buffer.
copy-region-to-rectangle). With numeric argument, delete it as
well.
insert-register).
The C-x r i r command inserts a text string if the register contains one, and inserts a rectangle if the register contains one.
See also the command sort-columns, which you can think of
as sorting a rectangle. See section Sorting Text.
You can save the window configuration of the selected frame in a register, or even the configuration of all windows in all frames, and restore the configuration later.
window-configuration-to-register).
frame-configuration-to-register).
Use C-x r j r to restore a window or frame configuration. This is the same command used to restore a cursor position. When you restore a frame configuration, any existing frames not included in the configuration become invisible. If you wish to delete these frames instead, use C-u C-x r j r.
If you visit certain file names frequently, you can visit them more conveniently if you put their names in registers. Here's the Lisp code used to put a file name in a register:
(set-register ?r '(file . name))
For example,
(set-register ?z '(file . "/gd/gnu/emacs/19.0/src/ChangeLog"))
puts the file name shown in register `z'.
To visit the file whose name is in register r, type C-x r j r. (This is the same command used to jump to a position or restore a frame configuration.)
Bookmarks are somewhat like registers in that they record positions you can jump to. Unlike registers, they have long names, and they persist automatically from one Emacs session to the next. The prototypical use of bookmarks is to record "where you were reading" in various files.
bookmark-set).
bookmark-jump).
list-bookmarks).
The prototypical use for bookmarks is to record one current position in each of several files. So the command C-x r m, which sets a bookmark, uses the visited file name as the default for the bookmark name. If you name each bookmark after the file it points to, then you can conveniently revisit any of those files with C-x r b, and move to the position of the bookmark at the same time.
To display a list of all your bookmarks in a separate buffer, type
C-x r l (list-bookmarks). If you switch to that buffer,
you can use it to edit your bookmark definitions. Type C-h m in
that buffer for more information about its special editing commands.
When you kill Emacs, Emacs offers to save your bookmark values in your default bookmark file, `~/.emacs-bkmrks', if you have changed any bookmark values. You can also save the bookmarks at any time with the M-x bookmark-save command. The bookmark commands load your default bookmark file automatically. This saving and loading is how bookmarks persist from one Emacs session to the next.
If you set the variable bookmark-save-flag to 1, then each
command that sets a bookmark will also save your bookmarks; this way,
you don't lose any bookmark values even if Emacs crashes. (The value,
if a number, says how many bookmark modifications should go by between
saving.)
Bookmark position values are saved with surrounding context, so that
bookmark-jump can find the proper position even if the file is
modified slightly. The variable bookmark-search-size says how
many characters of context to record, on each side of the bookmark's
position.
Here are some additional commands for working with bookmarks:
bookmark-write, to
work with other files of bookmark values in addition to your default
bookmark file.
Since only part of a large buffer fits in the window, Emacs tries to show the part that is likely to be interesting. The display control commands allow you to specify which part of the text you want to see.
recenter).
scroll-up).
scroll-down).
recenter).
scroll-left).
scroll-right).
set-selective-display).
The names of all scroll commands are based on the direction that the text
moves in the window. Thus, the command to scrolling forward is called
scroll-up, since the text moves up.
If a buffer contains text that is too large to fit entirely within a window that is displaying the buffer, Emacs shows a contiguous portion of the text. The portion shown always contains point.
Scrolling means moving text up or down in the window so that different parts of the text are visible. Scrolling forward means that text moves up, and new text appears at the bottom. Scrolling backward moves text down and new text appears at the top.
Scrolling happens automatically if you move point past the bottom or top of the window. You can also explicitly request scrolling with the commands in this section.
The most basic scrolling command is C-l (recenter) with
no argument. It clears the entire screen and redisplays all windows.
In addition, it scrolls the selected window so that point is halfway
down from the top of the window.
The scrolling commands C-v and M-v let you move all the text
in the window up or down a few lines. C-v (scroll-up) with an
argument shows you that many more lines at the bottom of the window, moving
the text and point up together as C-l might. C-v with a
negative argument shows you more lines at the top of the window.
M-v (scroll-down) is like C-v, but moves in the
opposite direction. The function keys NEXT and PRIOR are
equivalent to C-v and M-v.
To read the buffer a windowful at a time, use C-v with no argument.
It takes the last two lines at the bottom of the window and puts them at
the top, followed by nearly a whole windowful of lines not previously
visible. If point was in the text scrolled off the top, it moves to the
new top of the window. M-v with no argument moves backward with
overlap similarly. The number of lines of overlap across a C-v or
M-v is controlled by the variable next-screen-context-lines; by
default, it is two.
Another way to do scrolling is with C-l with a numeric argument. C-l does not clear the screen when given an argument; it only scrolls the selected window. With a positive argument n, it repositions text to put point n lines down from the top. An argument of zero puts point on the very top line. Point does not move with respect to the text; rather, the text and point move rigidly on the screen. C-l with a negative argument puts point that many lines from the bottom of the window. For example, C-u - 1 C-l puts point on the bottom line, and C-u - 5 C-l puts it five lines from the bottom. Just C-u as argument, as in C-u C-l, scrolls point to the center of the screen.
The C-M-l command (reposition-window) scrolls the current
window heuristically in a way designed to get useful information onto
the screen. For example, in a Lisp file, this command tries to get the
entire current defun onto the screen if possible.
Scrolling happens automatically if point has moved out of the visible
portion of the text when it is time to display. Usually the scrolling is
done so as to put point vertically centered within the window. However, if
the variable scroll-step has a nonzero value, an attempt is made to
scroll the buffer by that many lines; if that is enough to bring point back
into visibility, that is what is done.
The text in a window can also be scrolled horizontally. This means that each line of text is shifted sideways in the window, and one or more characters at the beginning of each line are not displayed at all. When a window has been scrolled horizontally in this way, text lines are truncated rather than continued (see section Continuation Lines), with a `$' appearing in the first column when there is text truncated to the left, and in the last column when there is text truncated to the right.
The command C-x < (scroll-left) scrolls the selected
window to the left by n columns with argument n. This moves
part of the beginning of each line off the left edge of the window.
With no argument, it scrolls by almost the full width of the window (two
columns less, to be precise).
C-x > (scroll-right) scrolls similarly to the right. The
window cannot be scrolled any farther to the right once it is displayed
normally (with each line starting at the window's left margin);
attempting to do so has no effect. This means that you don't have to
calculate the argument precisely for C-x >; any sufficiently large
argument will restore normally display.
Emacs has the ability to hide lines indented more than a certain number of columns (you specify how many columns). You can use this to get an overview of a part of a program.
To hide lines, type C-x $ (set-selective-display) with a
numeric argument n. Then lines with at least n columns of
indentation disappear from the screen. The only indication of their
presence is that three dots (`...') appear at the end of each
visible line that is followed by one or more invisible ones.
The commands C-n and C-p move across the invisible lines as if they were not there.
The invisible lines are still present in the buffer, and most editing commands see them as usual, so you may find point in the middle of invisible text. When this happens, the cursor appears at the end of the previous line, after the three dots. If point is at the end of the visible line, before the newline that ends it, the cursor appears before the three dots.
To make all lines visible again, type C-x $ with no argument.
Some European languages use accented letters and other special symbols. The ISO 8859 Latin-1 character set defines character codes for many European languages in the range 160 to 255.
Emacs can display those characters according to Latin-1, provided the terminal or font in use supports them. The M-x standard-display-european command toggles European character display mode. With a numeric argument, M-x standard-display-european enables European character display if and only if the argument is positive.
Some operating systems let you specify the language you are using by setting a locale. Emacs handles one common special case of this: if your locale name for character types contains the string `8859-1' or `88591', Emacs automatically enables European character display mode when it starts up.
Load the library iso-syntax to specify the correct syntactic
properties and case conversion table for the Latin-1 character set.
If your keyboard can send character codes 128 and up to represent ISO Latin-1 characters, execute the following expression to enable Emacs to understand them:
(set-input-mode (car (current-input-mode))
(nth 1 (current-input-mode))
0)
Otherwise, you can load the library iso-transl to turn the key
C-x 8 into a "compose character" prefix for entry of the extra
ISO Latin-1 printing characters. C-x 8 is good for insertion (in
the minibuffer as well as other buffers), for searching, and in any
other context where a key sequence is allowed. The ALT modifier key,
if you have one, serves the same purpose as C-x 8; use ALT
together with an accent character to modify the following letter.
If you enter non-ASCII ISO Latin-1 characters often, you might find ISO Accents mode convenient. When this minor mode is enabled, the characters ``', `'', `"', `^', `/' and `~' modify the following letter by adding the corresponding diacritical mark to it, if possible. To enable or disable ISO Accents mode, use the command M-x iso-accents-mode. This command affects only the current buffer.
To enter one of those six special characters, type the character, followed by a space. Some of those characters have a corresponding "dead key" accent character in the ISO Latin-1 character set; to enter that character, type the corresponding ASCII character twice. For example, " enters the Latin-1 character acute-accent (character code 0264).
In addition to the accented letters, you can use these special sequences in ISO Accents mode to enter certain other ISO Latin-1 characters:
This feature is available whenever a key sequence is expected: for ordinary insertion, for searching, and for certain command arguments.
To add the current line number of point to the mode line, enable Line Number mode with the command M-x line-number-mode. The line number appears before the buffer percentage pos, with the letter `L' to indicate what it is. See section Minor Modes, for more information about minor modes and about how to use this command.
If the buffer is very large (larger than the value of
line-number-display-limit), then the line number doesn't appear.
Emacs doesn't compute the line number when the buffer is large, because
that would be too slow.
Emacs can optionally display the time and system load in all mode lines. To enable this feature, type M-x display-time. The information added to the mode line usually appears after the buffer name, before the mode names and their parentheses. It looks like this:
hh:mmpm l.ll
Here hh and mm are the hour and minute, followed always by `am' or `pm'. l.ll is the average number of running processes in the whole system recently. (Some fields may be missing if your operating system cannot support them.)
The word `Mail' appears after the load level if there is mail for you that you have not read yet.
This section contains information for customization only. Beginning users should skip it.
The variable mode-line-inverse-video controls whether the mode
line is displayed in inverse video (assuming the terminal supports it);
nil means don't do so. See section The Mode Line. If you specify the
foreground color for the mode-line face, and
mode-line-inverse-video is non-nil, then the default
background color for that face is the usual foreground color.
See section Using Multiple Typefaces.
If the variable inverse-video is non-nil, Emacs attempts
to invert all the lines of the display from what they normally are.
If the variable visible-bell is non-nil, Emacs attempts
to make the whole screen blink when it would normally make an audible bell
sound. This variable has no effect if your terminal does not have a way
to make the screen blink.
When you reenter Emacs after suspending, Emacs normally clears the
screen and redraws the entire display. On some terminals with more than
one page of memory, it is possible to arrange the termcap entry so that
the `ti' and `te' strings (output to the terminal when Emacs
is entered and exited, respectively) switch between pages of memory so
as to use one page for Emacs and another page for other output. Then
you might want to set the variable no-redraw-on-reenter
non-nil; this tells Emacs to assume, when resumed, that the
screen page it is using still contains what Emacs last wrote there.
The variable echo-keystrokes controls the echoing of multi-character
keys; its value is the number of seconds of pause required to cause echoing
to start, or zero meaning don't echo at all. See section The Echo Area.
If the variable ctl-arrow is nil, control characters in
the buffer are displayed with octal escape sequences, all except newline
and tab. Altering the value of ctl-arrow makes it local to the
current buffer; until that time, the default value is in effect. The
default is initially t. See section `Display Tables' in The Emacs Lisp Reference Manual.
Normally, a tab character in the buffer is displayed as whitespace which
extends to the next display tab stop position, and display tab stops come
at intervals equal to eight spaces. The number of spaces per tab is
controlled by the variable tab-width, which is made local by
changing it, just like ctl-arrow. Note that how the tab character
in the buffer is displayed has nothing to do with the definition of
TAB as a command. The variable tab-width must have an
integer value between 1 and 1000, inclusive.
If you set the variable selective-display-ellipses to nil,
the three dots do not appear at the end of a line that precedes invisible
lines. Then there is no visible indication of the invisible lines.
This variable too becomes local automatically when set.
If the variable truncate-lines is non-nil, then each
line of text gets just one screen line for display; if the text line is
too long, display shows only the part that fits. If
truncate-lines is nil, then long text lines display as
more than one screen line, enough to show the whole text of the line.
See section Continuation Lines. Altering the value of truncate-lines
makes it local to the current buffer; until that time, the default value
is in effect. The default is initially nil.
If the variable truncate-partial-width-windows is
non-nil, it forces truncation rather than continuation in any
window less than the full width of the screen or frame, regardless of
the value of truncate-lines. For information about side-by-side
windows, see section Splitting Windows. See also section `Display' in The Emacs Lisp Reference Manual.
The variable baud-rate holds the the output speed of the
terminal, as far as Emacs knows. Setting this variable does not change
the speed of actual data transmission, but the value is used for
calculations such as padding. It also affects decisions about whether
to scroll part of the screen or redraw it instead--even when using a
window system. (We designed it this way, despite the fact that a window
system has no true "output speed", to give you a way to tune these
decisions.)
Like other editors, Emacs has commands for searching for occurrences of a string. The principal search command is unusual in that it is incremental; it begins to search before you have finished typing the search string. There are also nonincremental search commands more like those of other editors.
Besides the usual replace-string command that finds all
occurrences of one string and replaces them with another, Emacs has a fancy
replacement command called query-replace which asks interactively
which occurrences to replace.
An incremental search begins searching as soon as you type the first character of the search string. As you type in the search string, Emacs shows you where the string (as you have typed it so far) would be found. When you have typed enough characters to identify the place you want, you can stop. Depending on what you plan to do next, you may or may not need to terminate the search explicitly with RET.
isearch-forward).
isearch-backward).
C-s starts an incremental search. C-s reads characters from the keyboard and positions the cursor at the first occurrence of the characters that you have typed. If you type C-s and then F, the cursor moves right after the first `F'. Type an O, and see the cursor move to after the first `FO'. After another O, the cursor is after the first `FOO' after the place where you started the search. Meanwhile, the search string `FOO' has been echoed in the echo area.
If you make a mistake in typing the search string, you can cancel characters with DEL. Each DEL cancels the last character of search string. This does not happen until Emacs is ready to read another input character; first it must either find, or fail to find, the character you want to erase. If you do not want to wait for this to happen, use C-g as described below.
When you are satisfied with the place you have reached, you can type RET, which stops searching, leaving the cursor where the search brought it. Also, any command not specially meaningful in searches stops the searching and is then executed. Thus, typing C-a would exit the search and then move to the beginning of the line. RET is necessary only if the next command you want to type is a printing character, DEL, RET, or another control character that is special within searches (C-q, C-w, C-r, C-s, C-y, M-y, M-r, or M-s).
Sometimes you search for `FOO' and find it, but not the one you expected to find. There was a second `FOO' that you forgot about, before the one you were looking for. In this event, type another C-s to move to the next occurrence of the search string. This can be done any number of times. If you overshoot, you can cancel some C-s characters with DEL.
After you exit a search, you can search for the same string again by typing just C-s C-s: the first C-s is the key that invokes incremental search, and the second C-s means "search again".
To reuse earlier search strings, use the search ring. The commands M-p and M-n move through the ring to pick a search string to reuse. These commands leave the selected search ring element in the minibuffer, where you can edit it. Type C-s or C-r to terminate editing the string and search for it.
If your string is not found at all, the echo area says `Failing I-Search'. The cursor is after the place where Emacs found as much of your string as it could. Thus, if you search for `FOOT', and there is no `FOOT', you might see the cursor after the `FOO' in `FOOL'. At this point there are several things you can do. If your string was mistyped, you can rub some of it out and correct it. If you like the place you have found, you can type RET or some other Emacs command to "accept what the search offered". Or you can type C-g, which removes from the search string the characters that could not be found (the `T' in `FOOT'), leaving those that were found (the `FOO' in `FOOT'). A second C-g at that point cancels the search entirely, returning point to where it was when the search started.
An upper-case letter in the search string makes the search case-sensitive. If you delete the upper-case character from the search string, it ceases to have this effect. See section Searching and Case.
If a search is failing and you ask to repeat it by typing another C-s, it starts again from the beginning of the buffer. Repeating a failing reverse search with C-r starts again from the end. This is called wrapping around. `Wrapped' appears in the search prompt once this has happened.
The C-g "quit" character does special things during searches; just what it does depends on the status of the search. If the search has found what you specified and is waiting for input, C-g cancels the entire search. The cursor moves back to where you started the search. If C-g is typed when there are characters in the search string that have not been found--because Emacs is still searching for them, or because it has failed to find them--then the search string characters which have not been found are discarded from the search string. With them gone, the search is now successful and waiting for more input, so a second C-g will cancel the entire search.
To search for a newline, type LFD (also known as C-j). To search for another control character such as control-S or carriage return, you must quote it by typing C-q first. This function of C-q is analogous to its meaning as an Emacs command: it causes the following character to be treated the way a graphic character would normally be treated in the same context. You can also specify a character by its octal code: enter C-q followed by three octal digits.
You can change to searching backwards with C-r. If a search fails because the place you started was too late in the file, you should do this. Repeated C-r keeps looking for more occurrences backwards. A C-s starts going forwards again. C-r in a search can be canceled with DEL.
If you know initially that you want to search backwards, you can use
C-r instead of C-s to start the search, because C-r as
a key runs a command (isearch-backward) to search backward.
The characters C-y and C-w can be used in incremental search to grab text from the buffer into the search string. This makes it convenient to search for another occurrence of text at point. C-w copies the word after point as part of the search string, advancing point over that word. Another C-s to repeat the search will then search for a string including that word. C-y is similar to C-w but copies all the rest of the current line into the search string. Both C-y and C-w convert the text they copy to lower case if the search is current not case-sensitive; this is so the search remains case-insensitive.
The character M-y copies text from the kill ring into the search string. It uses the same text that C-y as a command would yank. See section Yanking.
To customize the special characters that incremental search understands,
alter their bindings in the keymap isearch-mode-map.
Incremental search on a slow terminal uses a modified style of display that is designed to take less time. Instead of redisplaying the buffer at each place the search gets to, it creates a new single-line window and uses that to display the line that the search has found. The single-line window comes into play as soon as point gets outside of the text that is already on the screen.
When you terminate the search, the single-line window is removed. Then Emacs redisplays the window in which the search was done, to show its new position of point.
The slow terminal style of display is used when the terminal baud rate is
less than or equal to the value of the variable search-slow-speed,
initially 1200.
The number of lines to use in slow terminal search display is controlled
by the variable search-slow-window-lines. 1 is its normal value.
Emacs also has conventional nonincremental search commands, which require you to type the entire search string before searching begins.
To do a nonincremental search, first type C-s RET. This enters the minibuffer to read the search string; terminate the string with RET, and then the search takes place. If the string is not found, the search command gets an error.
The way C-s RET works is that the C-s invokes incremental search, which is specially programmed to invoke nonincremental search if the argument you give it is empty. (Such an empty argument would otherwise be useless.) C-r RET also works this way.
However, nonincremental searches performed using C-s RET do
not call search-forward right away. The first thing done is to see
if the next character is C-w, which requests a word search.
Forward and backward nonincremental searches are implemented by the
commands search-forward and search-backward. These
commands may be bound to keys in the usual manner. The feature that you
can get to them via the incremental search commands exists for
historical reasons, and to avoid the need to find suitable key sequences
for them.
Word search searches for a sequence of words without regard to how the words are separated. More precisely, you type a string of many words, using single spaces to separate them, and the string can be found even if there are multiple spaces, newlines or other punctuation between the words.
Word search is useful for editing a printed document made with a text formatter. If you edit while looking at the printed, formatted version, you can't tell where the line breaks are in the source file. With word search, you can search without having to know them.
Word search is a special case of nonincremental search and is invoked with C-s RET C-w. This is followed by the search string, which must always be terminated with RET. Being nonincremental, this search does not start until the argument is terminated. It works by constructing a regular expression and searching for that; see section Regular Expression Search.
Use C-r RET C-w to do backward word search.
Forward and backward word searches are implemented by the commands
word-search-forward and word-search-backward. These
commands may be bound to keys in the usual manner. The feature that you
can get to them via the incremental search commands exists for historical
reasons, and to avoid the need to find suitable key sequences for them.
A regular expression (regexp, for short) is a pattern that denotes a class of alternative strings to match, possibly infinitely many. In GNU Emacs, you can search for the next match for a regexp either incrementally or not.
Incremental search for a regexp is done by typing C-M-s
(isearch-forward-regexp). This command reads a search string
incrementally just like C-s, but it treats the search string as a
regexp rather than looking for an exact match against the text in the
buffer. Each time you add text to the search string, you make the
regexp longer, and the new regexp is searched for. To search backward
in the buffer, use C-M-r (isearch-backward-regexp).
All of the control characters that do special things within an ordinary incremental search have the same function in incremental regexp search. Typing C-s or C-r immediately after starting the search retrieves the last incremental search regexp used; that is to say, incremental regexp and non-regexp searches have independent defaults. They also have separate search rings that you can access with M-p and M-n.
If you type SPC in incremental regexp search, it matches any sequence of whitespace characters, including newlines. If you want to match just a space, type C-q SPC.
Note that adding characters to the regexp in an incremental regexp search can make the cursor move back and start again. For example, if you have searched for `foo' and you add `\|bar', the cursor backs up in case the first `bar' precedes the first `foo'.
Nonincremental search for a regexp is done by the functions
re-search-forward and re-search-backward. You can invoke
these with M-x, or bind them to keys, or invoke them by way of
incremental regexp search with C-M-s RET and C-M-r
RET.
Regular expressions have a syntax in which a few characters are special constructs and the rest are ordinary. An ordinary character is a simple regular expression which matches that same character and nothing else. The special characters are `$', `^', `.', `*', `+', `?', `[', `]' and `\'. Any other character appearing in a regular expression is ordinary, unless a `\' precedes it.
For example, `f' is not a special character, so it is ordinary, and therefore `f' is a regular expression that matches the string `f' and no other string. (It does not match the string `ff'.) Likewise, `o' is a regular expression that matches only `o'. (When case distinctions are being ignored, these regexps also match `F' and `O', but we consider this a generalization of "the same string", rather than an exception.)
Any two regular expressions a and b can be concatenated. The result is a regular expression which matches a string if a matches some amount of the beginning of that string and b matches the rest of the string.
As a simple example, we can concatenate the regular expressions `f' and `o' to get the regular expression `fo', which matches only the string `fo'. Still trivial. To do something nontrivial, you need to use one of the special characters. Here is a list of them.
grep.
Note: for historical compatibility, special characters are treated as ordinary ones if they are in contexts where their special meanings make no sense. For example, `*foo' treats `*' as ordinary since there is no preceding expression on which the `*' can act. It is poor practice to depend on this behavior; better to quote the special character anyway, regardless of where is appears.
For the most part, `\' followed by any character matches only that character. However, there are several exceptions: two-character sequences starting with `\' which have special meanings. The second character in the sequence is always an ordinary character on their own. Here is a table of `\' constructs.
The constructs that pertain to words and syntax are controlled by the setting of the syntax table (see section The Syntax Table).
Here is a complicated regexp, used by Emacs to recognize the end of a sentence together with any whitespace that follows. It is given in Lisp syntax to enable you to distinguish the spaces from the tab characters. In Lisp syntax, the string constant begins and ends with a double-quote. `\"' stands for a double-quote as part of the regexp, `\\' for a backslash as part of the regexp, `\t' for a tab and `\n' for a newline.
"[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"
This contains four parts in succession: a character set matching period, `?', or `!'; a character set matching close-brackets, quotes, or parentheses, repeated any number of times; an alternative in backslash-parentheses that matches end-of-line, a tab, or two spaces; and a character set matching whitespace characters, repeated any number of times.
To enter the same regexp interactively, you would type TAB to enter a tab, and C-q C-j to enter a newline. You would also type single slashes as themselves, instead of doubling them for Lisp syntax.
Incremental searches in Emacs normally ignore the case of the text they are searching through, if you specify the text in lower case. Thus, if you specify searching for `foo', then `Foo' and `foo' are also considered a match. Regexps, and in particular character sets, are included: `[ab]' would match `a' or `A' or `b' or `B'.
An upper-case letter in the incremental search string makes the search case-sensitive. Thus, searching for `Foo' does not find `foo' or `FOO'. This applies to regular expression search as well as to string search. The effect ceases if you delete the upper-case letter from the search string.
If you set the variable case-fold-search to nil, then
all letters must match exactly, including case. This is a per-buffer
variable; altering the variable affects only the current buffer, but
there is a default value which you can change as well. See section Local Variables.
This variable applies to nonincremental searches also, including those
performed by the replace commands (see section Replacement Commands).
Global search-and-replace operations are not needed as often in Emacs as they are in other editors(1), but they are available. In addition to the simple M-x replace-string command which is like that found in most editors, there is a M-x query-replace command which asks you, for each occurrence of the pattern, whether to replace it.
The replace commands all replace one string (or regexp) with one
replacement string. It is possible to perform several replacements in
parallel using the command expand-region-abbrevs. See section Controlling Abbrev Expansion.
To replace every instance of `foo' after point with `bar', use the command M-x replace-string with the two arguments `foo' and `bar'. Replacement happens only in the text after point, so if you want to cover the whole buffer you must go to the beginning first. All occurrences up to the end of the buffer are replaced; to limit replacement to part of the buffer, narrow to that part of the buffer before doing the replacement (see section Narrowing).
When replace-string exits, point is left at the last occurrence
replaced. The position of point where the replace-string command
was issued is remembered on the mark ring; use C-u C-SPC to
move back there.
A numeric argument restricts replacement to matches that are surrounded by word boundaries. The argument's value doesn't matter.
The M-x replace-string command replaces exact matches for a single string. The similar command M-x replace-regexp replaces any match for a specified pattern.
In replace-regexp, the newstring need not be constant: it
can refer to all or part of what is matched by the regexp.
`\&' in newstring stands for the entire match being replaced.
`\d' in newstring, where d is a digit, stands for
whatever matched the dth parenthesized grouping in regexp.
To include a `\' in the text to replace with, you must enter
`\\'. For example,
M-x replace-regexp RET c[ad]+r RET \&-safe RET
replaces (for example) `cadr' with `cadr-safe' and `cddr' with `cddr-safe'.
M-x replace-regexp RET \(c[ad]+r\)-safe RET \1 RET
performs the inverse transformation.
If the arguments to a replace command are in lower case, it preserves case when it makes a replacement. Thus, the command
M-x replace-string RET foo RET bar RET
replaces a lower case `foo' with a lower case `bar',
`FOO' with `BAR', and `Foo' with `Bar'. If upper
case letters are used in the second argument, they remain upper case
every time that argument is inserted. If upper case letters are used in
the first argument, the second argument is always substituted exactly as
given, with no case conversion. Likewise, if the variable
case-replace is set to nil, replacement is done without
case conversion. If case-fold-search is set to nil, case
is significant in matching occurrences of `foo' to replace; this
also inhibits case conversion of the replacement string.
If you want to change only some of the occurrences of `foo' to
`bar', not all of them, then you cannot use an ordinary
replace-string. Instead, use M-% (query-replace).
This command finds occurrences of `foo' one by one, displays each
occurrence and asks you whether to replace it. A numeric argument to
query-replace tells it to consider only occurrences that are
bounded by word-delimiter characters. This preserves case, just like
replace-string, provided case-replace is non-nil,
as it normally is.
Aside from querying, query-replace works just like
replace-string, and query-replace-regexp works just like
replace-regexp. The shortest way to type this command name is
M-x que SPC SPC SPC RET.
The things you can type when you are shown an occurrence of string or a match for regexp are:
query-replace, so if you want to do further replacement
you must use C-x ESC ESC RET to restart
(see section Repeating Minibuffer Commands).
query-replace.
Some other characters are aliases for the ones listed above: y, n and q are equivalent to SPC, DEL and RET.
Aside from this, any other character exits the query-replace,
and is then reread as part of a key sequence. Thus, if you type
C-k, it exits the query-replace and then kills to end of
line.
To restart a query-replace once it is exited, use C-x
ESC ESC, which repeats the query-replace because it
used the minibuffer to read its arguments. See section Repeating Minibuffer Commands.
See also section Transforming File Names in Dired, for Dired commands to rename, copy, or link files by replacing regexp matches in file names.
Here are some other commands that find matches for a regular expression. They all operate from point to the end of the buffer.
In this chapter we describe the commands that are especially useful for the times when you catch a mistake in your text just after you have made it, or change your mind while composing text on the fly.
The most fundamental command for correcting erroneous editing is the
undo command, C-x u or C-_. This command undoes a single
command (usually), a part of a command (in the case of
query-replace), or several consecutive self-inserting characters.
Consecutive repetitions of C-_ or C-x u undo earlier and
earlier changes, back to the limit of the undo information available.
See section Undoing Changes, for for more information.
delete-backward-char).
backward-kill-word).
backward-kill-sentence).
The DEL character (delete-backward-char) is the most
important correction command. It deletes the character before point.
When DEL follows a self-inserting character command, you can think
of it as canceling that command. However, avoid the mistake of thinking
of DEL as a general way to cancel a command!
When your mistake is longer than a couple of characters, it might be more convenient to use M-DEL or C-x DEL. M-DEL kills back to the start of the last word, and C-x DEL kills back to the start of the last sentence. C-x DEL is particularly useful when you change your mind about the phrasing of the text you are writing. M-DEL and C-x DEL save the killed text for C-y and M-y to retrieve. See section Yanking.
M-DEL is often useful even when you have typed only a few characters wrong, if you know you are confused in your typing and aren't sure exactly what you typed. At such a time, you cannot correct with DEL except by looking at the screen to see what you did. Often it requires less thought to kill the whole word and start again.
transpose-chars).
transpose-words).
transpose-sexps).
transpose-lines).
The common error of transposing two characters can be fixed, when they
are adjacent, with the C-t command (transpose-chars). Normally,
C-t transposes the two characters on either side of point. When
given at the end of a line, rather than transposing the last character of
the line with the newline, which would be useless, C-t transposes the
last two characters on the line. So, if you catch your transposition error
right away, you can fix it with just a C-t. If you don't catch it so
fast, you must move the cursor back to between the two transposed
characters. If you transposed a space with the last character of the word
before it, the word motion commands are a good way of getting there.
Otherwise, a reverse search (C-r) is often the best way.
See section Searching and Replacement.
M-t (transpose-words) transposes the word before point
with the word after point. It moves point forward over a word, dragging
the word preceding or containing point forward as well. The punctuation
characters between the words do not move. For example, `FOO, BAR'
transposes into `BAR, FOO' rather than `BAR FOO,'.
C-M-t (transpose-sexps) is a similar command for transposing
two expressions (see section Lists and Sexps), and C-x C-t (transpose-lines)
exchanges lines. They work like M-t except in determining the
division of the text into syntactic units.
A numeric argument to a transpose command serves as a repeat count: it tells the transpose command to move the character (word, sexp, line) before or containing point across several other characters (words, sexps, lines). For example, C-u 3 C-t moves the character before point forward across three other characters. It would change `f-!-oobar' into `oobf-!-ar'. This is equivalent to repeating C-t three times. C-u - 4 M-t moves the word before point backward across four words. C-u - C-M-t would cancel the effect of plain C-M-t.
A numeric argument of zero is assigned a special meaning (because otherwise a command with a repeat count of zero would do nothing): to transpose the character (word, sexp, line) ending after point with the one ending after the mark.
A very common error is to type words in the wrong case. Because of this, the word case-conversion commands M-l, M-u and M-c have a special feature when used with a negative argument: they do not move the cursor. As soon as you see you have mistyped the last word, you can simply case-convert it and go on typing. See section Case Conversion Commands.
This section describes the commands to check the spelling of a single word or of a portion of a buffer. These commands work with the spelling checker program Ispell, which is not part of Emacs.
ispell-word).
To check the spelling of the word around or next to point, and
optionally correct it as well, use the command M-$
(ispell-word). If the word is not correct, the command offers
you various alternatives for what to do about it.
To check the entire current buffer, use M-x ispell-buffer. Use M-x ispell-region to check just the current region. To check spelling in an email message you are writing, use M-x ispell-message; that checks the whole buffer, but does not check material that is indented or appears to be cited from other messages.
Each time these commands encounter an incorrect word, they ask you what to do. It displays a list of alternatives, usually including several "near-misses"---words that are close to the word being checked. Then you must type a character. Here are the valid responses:
query-replace so you
can replace it elsewhere in the buffer if you wish.
The command ispell-complete-word, which is bound to the key
M-TAB in Text mode and related modes, shows a list of
completions based on spelling correction. Insert the beginning of a
word, and then type M-TAB; the command displays a completion
list window. To choose one of the completions listed, click
Mouse-2 on it, or move the cursor there in the completions window
and type RET. See section Text Mode.
Once started, the Ispell subprocess continues to run (waiting for something to do), so that subsequent spell checking commands complete more quickly. If you want to get rid of the Ispell process, use M-x ispell-kill-ispell. This is not usually necessary, since the process uses no time except when you do spelling correction.
Ispell uses two dictionaries: the standard dictionary and your private
dictionary. The variable ispell-dictionary specifies the file
name of the standard dictionary to use. A value of nil says to
use the default dictionary. The command M-x
ispell-change-dictionary sets this variable and then restarts the
Ispell subprocess, so that it will use a different dictionary.
The operating system stores data permanently in named files. So most of the text you edit with Emacs comes from a file and is ultimately stored in a file.
To edit a file, you must tell Emacs to read the file and prepare a buffer containing a copy of the file's text. This is called visiting the file. Editing commands apply directly to text in the buffer; that is, to the copy inside Emacs. Your changes appear in the file itself only when you save the buffer back into the file.
In addition to visiting and saving files, Emacs can delete, copy, rename, and append to files, keep multiple versions of them, and operate on file directories.
Most Emacs commands that operate on a file require you to specify the file name. (Saving and reverting are exceptions; the buffer knows which file name to use for them.) You enter the file name using the minibuffer (see section The Minibuffer). Completion is available, to make it easier to specify long file names. See section Completion.
For most operations, there is a default file name which is used if you type just RET to enter an empty argument. Normally the default file name is the name of the file visited in the current buffer; this makes it easy to operate on that file with any of the Emacs file commands.
Each buffer has a default directory, normally the same as the
directory of the file visited in that buffer. When you enter a file
name without a directory, the default directory is used. If you specify
a directory in a relative fashion, with a name that does not start with
a slash, it is interpreted with respect to the default directory. The
default directory is kept in the variable default-directory,
which has a separate value in every buffer.
For example, if the default file name is `/u/rms/gnu/gnu.tasks' then the default directory is `/u/rms/gnu/'. If you type just `foo', which does not specify a directory, it is short for `/u/rms/gnu/foo'. `../.login' would stand for `/u/rms/.login'. `new/foo' would stand for the file name `/u/rms/gnu/new/foo'.
The command M-x pwd prints the current buffer's default
directory, and the command M-x cd sets it (to a value read using
the minibuffer). A buffer's default directory changes only when the
cd command is used. A file-visiting buffer's default directory
is initialized to the directory of the file that is visited there. If
you create a buffer with C-x b, its default directory is copied
from that of the buffer that was current at the time.
The default directory actually appears in the minibuffer when the
minibuffer becomes active to read a file name. This serves two
purposes: it shows you what the default is, so that you can type
a relative file name and know with certainty what it will mean, and it
allows you to edit the default to specify a different directory.
This insertion of the default directory is inhibited if the variable
insert-default-directory is set to nil.
Note that it is legitimate to type an absolute file name after you enter the minibuffer, ignoring the presence of the default directory name as part of the text. The final minibuffer contents may look invalid, but that is not so. For example, if the minibuffer starts out with `/usr/tmp/' and you add `/x1/rms/foo', you get `/usr/tmp//x1/rms/foo'; but Emacs ignores everything through the first slash in the double slash; the result is `/x1/rms/foo'. See section Minibuffers for File Names.
You can refer to files on other machines using a special file name syntax:
/host:filename /user@host:filename
When you do this, Emacs uses the FTP program to read and write files on the specified host. It logs in through FTP using your user name or the name user. It may ask you for a password from time to time; this is used for logging in on host.
`$' in a file name is used to substitute environment variables. For example, if you have used the shell command `export FOO=rms/hacks' to set up an environment variable named `FOO', then you can use `/u/$FOO/test.c' or `/u/${FOO}/test.c' as an abbreviation for `/u/rms/hacks/test.c'. The environment variable name consists of all the alphanumeric characters after the `$'; alternatively, it may be enclosed in braces after the `$'. Note that shell commands to set environment variables affect Emacs only if done before Emacs is started.
To access a file with `$' in its name, type `$$'. This pair
is converted to a single `$' at the same time as variable substitution
is performed for single `$'. The Lisp function that performs the
substitution is called substitute-in-file-name. The substitution
is performed only on file names read as such using the minibuffer.
find-file).
find-file-read-only).
find-alternate-file).
find-file-other-window). Don't
change the selected window.
find-file-other-frame). Don't
change the selected frame.
Visiting a file means copying its contents into an Emacs buffer so you can edit them. Emacs makes a new buffer for each file that you visit. We say that this buffer is visiting the file that it was created to hold. Emacs constructs the buffer name from the file name by throwing away the directory, keeping just the name proper. For example, a file named `/usr/rms/emacs.tex' would get a buffer named `emacs.tex'. If there is already a buffer with that name, a unique name is constructed by appending `<2>', `<3>', or so on, using the lowest number that makes a name that is not already in use.
Each window's mode line shows the name of the buffer that is being displayed in that window, so you can always tell what buffer you are editing.
The changes you make with editing commands are made in the Emacs buffer. They do not take effect in the file that you visited, or any place permanent, until you save the buffer. Saving the buffer means that Emacs writes the current contents of the buffer into its visited file. See section Saving Files.
If a buffer contains changes that have not been saved, we say the buffer is modified. This is important because it implies that some changes will be lost if the buffer is not saved. The mode line displays two stars near the left margin to indicate that the buffer is modified.
To visit a file, use the command C-x C-f (find-file). Follow
the command with the name of the file you wish to visit, terminated by a
RET.
The file name is read using the minibuffer (see section The Minibuffer), with defaulting and completion in the standard manner (see section File Names). While in the minibuffer, you can abort C-x C-f by typing C-g.
Your confirmation that C-x C-f has completed successfully is the appearance of new text on the screen and a new buffer name in the mode line. If the specified file does not exist and could not be created, or cannot be read, then you get an error, with an error message displayed in the echo area.
If you visit a file that is already in Emacs, C-x C-f does not make another copy. It selects the existing buffer containing that file. However, before doing so, it checks that the file itself has not changed since you visited or saved it last. If the file has changed, a warning message is printed. See section Protection against Simultaneous Editing.
What if you want to create a new file? Just visit it. Emacs prints `(New File)' in the echo area, but in other respects behaves as if you had visited an existing empty file. If you make any changes and save them, the file is created.
If the file you specify is actually a directory, C-x C-f invokes
Dired, the Emacs directory browser so that you can "edit" the contents
of the directory (see section Dired, the Directory Editor). Dired is a convenient way to delete,
look at, or operate on the files in the directory. However, if the
variable find-file-run-dired is nil, then it is an error
to try to visit a directory.
If you visit a file that the operating system won't let you modify,
Emacs makes the buffer read-only, so that you won't go ahead and make
changes that you'll have trouble saving afterward. You can make the
buffer writable with C-x C-q (vc-toggle-read-only).
See section Miscellaneous Buffer Operations.
Occasionally you might want to visit a file as read-only in order to
protect yourself from entering changes accidentally; do so by visiting
the file with the command C-x C-r (find-file-read-only).
If you visit a nonexistent file unintentionally (because you typed the
wrong file name), use the C-x C-v command
(find-alternate-file) to visit the file you really wanted.
C-x C-v is similar to C-x C-f, but it kills the current
buffer (after first offering to save it if it is modified). When it
reads the file name to visit, it inserts the entire default file name in
the buffer, with point just after the directory part; this is convenient
if you made a slight error in typing the name.
C-x 4 f (find-file-other-window) is like C-x C-f
except that the buffer containing the specified file is selected in another
window. The window that was selected before C-x 4 f continues to
show the same buffer it was already showing. If this command is used when
only one window is being displayed, that window is split in two, with one
window showing the same buffer as before, and the other one showing the
newly requested file. See section Multiple Windows.
C-x 5 f (find-file-other-frame) is similar, but opens a
new frame, or makes visible any existing frame showing the file you
seek. This feature is available only when you are using a window
system. See section Frames and X Windows.
Two special hook variables allow extensions to modify the operation of
visiting files. Visiting a file that does not exist runs the functions
in the list find-file-not-found-hooks; this variable holds a list
of functions, and the functions are called one by one until one of them
returns non-nil. Any visiting of a file, whether extant or not,
expects find-file-hooks to contain a list of functions and calls
them all, one by one. In both cases the functions receive no
arguments. Of these two variables, find-file-not-found-hooks
takes effect first. These variables are not normal hooks, and
their names end in `-hooks' rather than `-hook' to indicate
that fact. See section Hooks.
There are several ways to specify automatically the major mode for editing the file (see section How Major Modes are Chosen), and to specify local variables defined for that file (see section Local Variables in Files).
Saving a buffer in Emacs means writing its contents back into the file that was visited in the buffer.
save-buffer).
save-some-buffers).
not-modified).
write-file).
When you wish to save the file and make your changes permanent, type
C-x C-s (save-buffer). After saving is finished, C-x C-s
displays a message like this:
Wrote /u/rms/gnu/gnu.tasks
If the selected buffer is not modified (no changes have been made in it since the buffer was created or last saved), saving is not really done, because it would have no effect. Instead, C-x C-s displays a message like this in the echo area:
(No changes need to be written)
The command C-x s (save-some-buffers) offers to save any
or all modified buffers. It asks you what to do with each buffer. The
possible responses are analogous to those of query-replace:
save-some-buffers without any more saving.
save-some-buffers without even asking
about other buffers.
save-some-buffers, which asks the
question again.
C-x C-c, the key sequence to exit Emacs, invokes
save-some-buffers and therefore asks the same questions.
If you have changed a buffer but you do not want to save the changes,
you should take some action to prevent it. Otherwise, each time you use
C-x s or C-x C-c, you are liable to save this buffer by
mistake. One thing you can do is type M-~ (not-modified),
which clears out the indication that the buffer is modified. If you do
this, none of the save commands will believe that the buffer needs to be
saved. (`~' is often used as a mathematical symbol for `not'; thus
M-~ is `not', metafied.) You could also use
set-visited-file-name (see below) to mark the buffer as visiting
a different file name, one which is not in use for anything important.
Alternatively, you can cancel all the changes made since the file was
visited or saved, by reading the text from the file again. This is
called reverting. See section Reverting a Buffer. You could also undo all the
changes by repeating the undo command C-x u until you have undone
all the changes; but reverting is easier.
M-x set-visited-file-name alters the name of the file that the
current buffer is visiting. It reads the new file name using the
minibuffer. Then it specifies the visited file name and changes the
buffer name correspondingly (as long as the new name is not in use).
set-visited-file-name does not save the buffer in the newly
visited file; it just alters the records inside Emacs in case you do
save later. It also marks the buffer as "modified" so that C-x
C-s in that buffer will save.
If you wish to mark the buffer as visiting a different file and save it
right away, use C-x C-w (write-file). It is precisely
equivalent to set-visited-file-name followed by C-x C-s.
C-x C-s used on a buffer that is not visiting with a file has the
same effect as C-x C-w; that is, it reads a file name, marks the
buffer as visiting that file, and saves it there. The default file name in
a buffer that is not visiting a file is made by combining the buffer name
with the buffer's default directory.
If Emacs is about to save a file and sees that the date of the latest version on disk does not match what Emacs last read or wrote, Emacs notifies you of this fact, because it probably indicates a problem caused by simultaneous editing and requires your immediate attention. See section Protection against Simultaneous Editing.
If the variable require-final-newline is non-nil, Emacs
puts a newline at the end of any file that doesn't already end in one,
every time a file is saved or written.
On most operating systems, rewriting a file automatically destroys all
record of what the file used to contain. Thus, saving a file from Emacs
throws away the old contents of the file--or it would, except that
Emacs carefully copies the old contents to another file, called the
backup file, before actually saving. (This assumes that the
variable make-backup-files is non-nil. Backup files are
not written if this variable is nil.)
At your option, Emacs can keep either a single backup file or a series of numbered backup files for each file that you edit.
Emacs makes a backup for a file only the first time the file is saved from one buffer. No matter how many times you save a file, its backup file continues to contain the contents from before the file was visited. Normally this means that the backup file contains the contents from before the current editing session; however, if you kill the buffer and then visit the file again, a new backup file will be made by the next save.
If you choose to have a single backup file (this is the default), the backup file's name is constructed by appending `~' to the file name being edited; thus, the backup file for `eval.c' would be `eval.c~'.
If you choose to have a series of numbered backup files, backup file names are made by appending `.~', the number, and another `~' to the original file name. Thus, the backup files of `eval.c' would be called `eval.c.~1~', `eval.c.~2~', and so on, through names like `eval.c.~259~' and beyond.
If protection stops you from writing backup files under the usual names, the backup file is written as `%backup%~' in your home directory. Only one such file can exist, so only the most recently made such backup is available.
The choice of single backup or numbered backups is controlled by the
variable version-control. Its possible values are
t
nil
never
You can set version-control locally in an individual buffer to
control the making of backups for that buffer's file. For example,
Rmail mode locally sets version-control to never to make sure
that there is only one backup for an Rmail file. See section Local Variables.
If you set the environment variable VERSION_CONTROL, to tell
various GNU utilities what to do with backup files, Emacs also obeys the
environment variable by setting the Lisp variable version-control
accordingly at startup. If the environment variable's value is `t'
or `numbered', then version-control becomes t; if the
value is `nil' or `existing', then version-control
becomes nil; if it is `never' or `simple', then
version-control becomes never.
For files under version control (see section Version Control), the
variable vc-make-backup-files determines whether to make backup
files. By default, it is nil, since backup files are redundant
when you store all the previous versions in a version control system.
See section Editing with Version Control.
To prevent unlimited consumption of disk space, Emacs can delete numbered backup versions automatically. Generally Emacs keeps the first few backups and the latest few backups, deleting any in between. This happens every time a new backup is made.
The two variables kept-old-versions and
kept-new-versions control this deletion. Their values are,
respectively the number of oldest (lowest-numbered) backups to keep and
the number of newest (highest-numbered) ones to keep, each time a new
backup is made. Recall that these values are used just after a new
backup version is made; that newly made backup is included in the count
in kept-new-versions. By default, both variables are 2.
If delete-old-versions is non-nil, the excess
middle versions are deleted without a murmur. If it is nil, the
default, then you are asked whether the excess middle versions should
really be deleted.
Dired's . (Period) command can also be used to delete old versions. See section Deleting Files with Dired.
Backup files can be made by copying the old file or by renaming it. This makes a difference when the old file has multiple names. If the old file is renamed into the backup file, then the alternate names become names for the backup file. If the old file is copied instead, then the alternate names remain names for the file that you are editing, and the contents accessed by those names will be the new contents.
The method of making a backup file may also affect the file's owner and group. If copying is used, these do not change. If renaming is used, you become the file's owner, and the file's group becomes the default (different operating systems have different defaults for the group).
Having the owner change is usually a good idea, because then the owner
always shows who last edited the file. Also, the owners of the backups
show who produced those versions. Occasionally there is a file whose
owner should not change; it is a good idea for such files to contain
local variable lists to set backup-by-copying-when-mismatch
locally (see section Local Variables in Files).
The choice of renaming or copying is controlled by three variables.
Renaming is the default choice. If the variable
backup-by-copying is non-nil, copying is used. Otherwise,
if the variable backup-by-copying-when-linked is non-nil,
then copying is used for files that have multiple names, but renaming
may still used when the file being edited has only one name. If the
variable backup-by-copying-when-mismatch is non-nil, then
copying is used if renaming would cause the file's owner or group to
change.
Simultaneous editing occurs when two users visit the same file, both make changes, and then both save them. If nobody were informed that this was happening, whichever user saved first would later find that his changes were lost. On some systems, Emacs notices immediately when the second user starts to change the file, and issues an immediate warning.
For the sake of systems where that is not possible, and in case someone else proceeds to change the file despite the warning, Emacs also checks when the file is saved, and issues a second warning if you are about to overwrite a file containing another user's changes. You can prevent loss of the other user's work by taking the proper corrective action at that time.
When you make the first modification in an Emacs buffer that is visiting a file, Emacs records that the file is locked by you. (It does this by writing another file in a directory reserved for this purpose.) The lock is removed when you save the changes. The idea is that the file is locked whenever an Emacs buffer visiting it has unsaved changes.
If you begin to modify the buffer while the visited file is locked by
someone else, this constitutes a collision. When Emacs detects a
collision, it asks you what to do, by calling the Lisp function
ask-user-about-lock. You can redefine this function for the sake
of customization. The standard definition of this function asks you a
question and accepts three possible answers:
file-locked) and the modification you
were trying to make in the buffer does not actually take place.
Note that locking works on the basis of a file name; if a file has multiple names, Emacs does not realize that the two names are the same file and cannot prevent two users from editing it simultaneously under different names. However, basing locking on names means that Emacs can interlock the editing of new files that will not really exist until they are saved.
Some systems are not configured to allow Emacs to make locks. On these systems, Emacs cannot detect trouble in advance, but it still can detect the collision when you try to save a file and overwrite someone else's changes.
Every time Emacs saves a buffer, it first checks the last-modification date of the existing file on disk to verify that it has not changed since the file was last visited or saved. If the date does not match, it implies that changes were made in the file in some other way, and these changes are about to be lost if Emacs actually does save. To prevent this, Emacs prints a warning message and asks for confirmation before saving. Occasionally you will know why the file was changed and know that it does not matter; then you can answer yes and proceed. Otherwise, you should cancel the save with C-g and investigate the situation.
The first thing you should do when notified that simultaneous editing has
already taken place is to list the directory with C-u C-x C-d
(see section Listing a File Directory). This shows the file's current
author. You should attempt to contact him to warn him not to continue
editing. Often the next step is to save the contents of your Emacs buffer
under a different name, and use diff to compare the two
files.
Simultaneous editing checks are also made when you visit with C-x C-f a file that is already visited and when you start to modify a file. This is not strictly necessary, but it can cause you to find out about the collision earlier, when perhaps correction takes less work.
If you have made extensive changes to a file and then change your mind about them, you can get rid of them by reading in the previous version of the file. To do this, use M-x revert-buffer, which operates on the current buffer. Since reverting a buffer unintentionally could lose a lot of work, you must confirm this command with yes.
revert-buffer keeps point at the same distance (measured in
characters) from the beginning of the file. If the file was edited only
slightly, you will be at approximately the same piece of text after
reverting as before. If you have made drastic changes, the same value of
point in the old file may address a totally different piece of text.
Reverting marks the buffer as "not modified" until another change is made.
Some kinds of buffers whose contents reflect data bases other than files,
such as Dired buffers, can also be reverted. For them, reverting means
recalculating their contents from the appropriate data base. Buffers
created randomly with C-x b cannot be reverted; revert-buffer
reports an error when asked to do so.
Emacs saves all the visited files from time to time (based on counting your keystrokes) without being asked. This is called auto-saving. It prevents you from losing more than a limited amount of work if the system crashes.
When Emacs determines that it is time for auto-saving, each buffer is considered, and is auto-saved if auto-saving is turned on for it and it has been changed since the last time it was auto-saved. The message `Auto-saving...' is displayed in the echo area during auto-saving, if any files are actually auto-saved. Errors occurring during auto-saving are caught so that they do not interfere with the execution of commands you have been typing.
Auto-saving does not normally save in the files that you visited, because it can be very undesirable to save a program that is in an inconsistent state when you have made half of a planned change. Instead, auto-saving is done in a different file called the auto-save file, and the visited file is changed only when you request saving explicitly (such as with C-x C-s).
Normally, the auto-save file name is made by appending `#' to the
front and rear of the visited file name. Thus, a buffer visiting file
`foo.c' is auto-saved in a file `#foo.c#'. Most buffers that
are not visiting files are auto-saved only if you request it explicitly;
when they are auto-saved, the auto-save file name is made by appending
`#%' to the front and `#' to the rear of buffer name. For
example, the `*mail*' buffer in which you compose messages to be
sent is auto-saved in a file named `#%*mail*#'. Auto-save file
names are made this way unless you reprogram parts of Emacs to do
something different (the functions make-auto-save-file-name and
auto-save-file-name-p). The file name to be used for auto-saving
in a buffer is calculated when auto-saving is turned on in that buffer.
When you delete a substantial part of the text in a large buffer, auto save turns off temporarily in that buffer. This is so that if you delete text accidentally, it is likely to remain present in the auto save file. To reenable auto-saving after this happens, simply save the file explicitly with C-x C-s. Using C-u 1 M-x auto-save-mode also cancels this particular state.
If you want auto-saving to be done in the visited file, set the variable
auto-save-visited-file-name to be non-nil. In this mode,
there is really no difference between auto-saving and explicit saving.
A buffer's auto-save file is deleted when you save the buffer in its
visited file. To inhibit this, set the variable delete-auto-save-files
to nil. Changing the visited file name with C-x C-w or
set-visited-file-name renames any auto-save file to go with
the new visited name.
When you delete a large amount of a buffer's text, auto-saving turns off in that buffer. This is because if you deleted the text unintentionally, you might find the auto-save file more useful if it contains the deleted text. To restart auto-saving in that buffer, save the buffer with C-x C-s, or use M-x auto-save.
Each time you visit a file, auto-saving is turned on for that file's
buffer if the variable auto-save-default is non-nil (but not
in batch mode; see section Entering and Exiting Emacs). The default for this variable is
t, so auto-saving is the usual practice for file-visiting buffers.
Auto-saving can be turned on or off for any existing buffer with the
command M-x auto-save-mode. Like other minor mode commands, M-x
auto-save-mode turns auto-saving on with a positive argument, off with a
zero or negative argument; with no argument, it toggles.
Emacs does auto-saving periodically based on counting how many characters
you have typed since the last time auto-saving was done. The variable
auto-save-interval specifies how many characters there are between
auto-saves. By default, it is 300.
Auto-saving also takes place when you stop typing for a while. The
variable auto-save-timeout says how many seconds Emacs should
wait before it does an auto save (and perhaps also a garbage
collection). (The actual time period is longer if the current buffer is
long; this is a heuristic which aims to keep out of your way when you
are editing long buffers in which auto-save takes an appreciable amount
of time.) Auto-saving during idle periods accomplishes two things:
first, it makes sure all your work is saved if you go away from the
terminal for a while; second, it may avoid some auto-saving while you
are actually typing.
Emacs also does auto-saving whenever it gets a fatal error. This
includes killing the Emacs job with a shell command such as kill
%emacs, or disconnecting a phone line or network connection.
You can request an auto-save explicitly with the command M-x do-auto-save.
The way to use the contents of an auto-save file to recover from a loss of data is with the command M-x recover-file RET file RET. This visits file and then (after your confirmation) restores the contents from from its auto-save file `#file#'. You can then save with C-x C-s to put the recovered text into file itself. For example, to recover file `foo.c' from its auto-save file `#foo.c#', do:
M-x recover-file RET foo.c RET yes RET C-x C-s
Before asking for confirmation, M-x recover-file displays a directory listing describing the specified file and the auto-save file, so you can compare their sizes and dates. If the auto-save file is older, M-x recover-file does not offer to read it.
Symbolic links and hard links both make it possible for several file names to refer to the same file. Hard links are alternate names that refer directly to the file; all the names are equally valid, and no one of them is preferred. By contrast, a symbolic link is a kind of defined alias: when `foo' is a symbolic link to `bar', you can use either name to refer to the file, but `bar' is the real name, while `foo' is just an alias. More complex cases occur when symbolic links point to directories.
If you visit two names for the same file, normally Emacs makes two different buffers, but it warns you about the situation.
If you wish to avoid visiting the same file in two buffers under
different names, set the variable find-file-existing-other-name
to a non-nil value. Then find-file uses the existing
buffer visiting the file, no matter which of the file's names you
specify.
If the variable find-file-visit-truename is non-nil,
then the file name recorded for a buffer is the file's truename
(made by replacing all symbolic links with their target names), rather
than the name you specify. Setting find-file-visit-truename also
implies the effect of find-file-existing-other-name.
Version control systems are packages that can record multiple versions of a source file, usually storing the unchanged parts of the file just once. Version control systems also record history information such as the creation time of each version, who created it, and a description of what was changed in that version.
The GNU project recommends the version control system known as RCS, which is free software and available from the Free Software Foundation. Emacs supports use of either RCS or SCCS (a proprietary, but widely used, version control system that is not quite as powerful as RCS) through a facility called VC. The same Emacs commands work with either RCS or SCCS, so you hardly have to know which one of them you are using.
When a file is under version control, we also say that it is registered in the version control system. Each registered file has a corresponding master file which represents the file's present state plus its change history, so that you can reconstruct from it either the current version or any specified earlier version. Usually the master file also records a log entry for each version describing what was changed in that version.
The file that is maintained under version control is sometimes called the work file corresponding to its master file.
To examine a file, you check it out. This extracts a version of the source file (typically, the most recent) from the master file. If you want to edit the file, you must check it out locked. Only one user can do this at a time for any given source file. (This kind of locking is completely unrelated to the locking that Emacs uses to detect simultaneous editing of a file.)
When you are done with your editing, you must check in the new version. This records the new version in the master file, and unlocks the source file so that other people can lock it and thus modify it.
Checkin and checkout are the basic operations of version control. You
can do both of them with a single Emacs command: C-x C-q
(vc-toggle-read-only).
A snapshot is a coherent collection of versions of the various files that make up a program. See section Snapshots.
When you visit a file that is maintained using version control, the mode line displays `RCS' or `SCCS' to inform you that version control is in use, and also (in case you care) which low-level system the file is actually stored in. Normally, such a source file is read-only, and the mode line indicates this with `%%'. With RCS, the mode line also indicates the number of the head version, which is normally also the version you are looking at.
These are the commands for editing a file maintained with version control:
(C-x v is the prefix key for version control commands; all of these commands except for C-x C-q start with C-x v.)
When you want to modify a file maintained with version control, type
C-x C-q (vc-toggle-read-only). This checks out the
file, and tells RCS or SCCS to lock the file. This means making the
file writable for you (but not for anyone else).
When you are finished editing the file, type C-x C-q again. When used on a file that is checked out, this command checks the file in. But check-in does not start immediately; first, you must enter the log entry---a description of the changes in the new version. C-x C-q pops up a buffer for you to enter this in. When you are finished typing in the log entry, type C-c C-c to terminate it; this is when actual check-in takes place.
Checking in your changes unlocks the file, so that other users can lock it and modify it.
To specify the version number for the new version, use the command
C-u C-x v v to do the checkin. C-x v v
(vc-next-action) is the command that C-x C-q uses to do the
"real work" when the visited file uses version control. When used for
checkin, and given a numeric argument, it reads the version number with
the minibuffer.
Emacs does not save backup files for source files that are maintained
with version control. If you want to make backup files despite version
control, set the variable vc-make-backup-files to a
non-nil value.
Normally the work file exists all the time, whether it is locked or
not. If you set vc-keep-workfiles to nil, then checking
in a new version with C-x C-q deletes the work file; but any
attempt to visit the file with Emacs creates it again.
It is not impossible to lock a file that someone else has locked. If you try to check out a file that is locked, C-x C-q asks you whether you want to "steal the lock." If you say yes, the file becomes locked by you, but a message is sent to the person who had formerly locked the file, to inform him of what has happened. The mode line indicates that a file is locked by someone else by displaying the login name of that person, before the version number.
If you want to discard your current set of changes and revert to the
last version checked in, use C-x v u (vc-revert-buffer).
This cancels your last check-out, leaving the file unlocked. If you want
to make a different set of changes, you must first check the file out
again. C-x v u requires confirmation, unless it sees that
you haven't made any changes since the last checked-in version.
C-x v u is also the command to use to unlock a file if you lock it and then decide not to change it.
You can cancel a change after checking it in, with C-x v c
(vc-cancel-version). This command discards all record of the
most recent checked in version. C-x v c also offers to revert
your workfile and buffer to the previous version (the one that precedes
the version that is deleted). If you say no, then the buffer and
workfile do not change.
Be careful when invoking C-x v c, as it is easy to throw away a lot of work with it. To help you be careful, this command always requires confirmation with yes.
You can register the visited file for version control using
C-x v i (vc-register). If the variable
vc-default-back-end is non-nil, it specifies which version
control system to use; otherwise, this uses RCS if it is installed on
your system, and SCCS otherwise. After C-x v i, the file is
unlocked and read-only. Type C-x C-q if you wish to lock and edit
it.
The initial version number for a newly registered file is 1.1. To specify a different number, give C-x v i a numeric argument; then it reads the initial version number using the minibuffer.
If vc-initial-comment is non-nil, C-x v i reads
an initial comment (much like a log entry) to describe the purpose of
this source file.
If vc-suppress-confirm is non-nil, then C-x C-q
and C-x v i can save the current buffer without asking, and
C-x v u also operates without asking for confirmation.
(This variable does not affect C-x v c; that is so drastic
that it should always ask for confirmation.)
VC mode does much of its work by running the shell commands for RCS
and SCCS. If vc-command-messages is non-nil, VC displays
messages to indicate which shell commands it runs, and additional
messages when the commands finish.
Normally, VC assumes that it can deduce the locked/unlocked state of files by looking at the file permissions of the work file; this is fast. However, if the `RCS' or `SCCS' subdirectory is actually a symbolic link, then VC does not trust the file permissions to reflect this status.
You can specify the criterion for whether to trust the file permissions
by setting the variable vc-mistrust-permissions. Its value may
be t (always mistrust the file permissions and check the master
file), nil (always trust the file permissions), or a function of
one argument which makes the decision. The argument is the directory
name of the `RCS' or `SCCS' subdirectory. A non-nil
value from the function says to mistrust the file permissions. If you
find that the file permissions of work files are changed erroneously,
set vc-mistrust-permissions to t. Then VC always checks
the master file to determine the file's status.
You can specify additional directories to search for version control
programs by setting the variable vc-path. These directories are
searched before the usual search path. But the proper files are usually
found automatically.
When you're editing an initial comment or log entry for inclusion in a master file, finish your entry by typing C-c C-c.
vc-finish-logentry).
This finishes check-in.
To abort check-in, just don't type C-c C-c in that buffer. You can switch buffers and do other editing. As long as you don't try to check in another file, the entry you were editing remains in its buffer, and you can go back to that buffer at any time to complete the check-in.
If you change several source files for the same reason, it is often convenient to specify the same log entry for many of the files. To do this, use the history of previous log entries. The commands M-n, M-p, M-s and M-r for doing this work just like the minibuffer history commands (except that these versions are used outside the minibuffer).
Each time you check in a file, the log entry buffer is put into VC Log
mode, which involves running two hooks: text-mode-hook and
vc-log-mode-hook. See section Hooks.
If you use RCS for a program and also maintain a change log file for it (see section Change Logs), you can generate change log entries automatically from the version control log entries:
vc-update-change-log).
This command works with RCS only; it does not work with SCCS.
For example, suppose the first line of `ChangeLog' is dated 10 April 1992, and that the only check-in since then was by Nathaniel Bowditch to `rcs2log' on 8 May 1992 with log text `Ignore log messages that start with `#'.'. Then C-x v a visits `ChangeLog' and inserts text like this:
@medbreak
Fri May 8 21:45:00 1992 Nathaniel Bowditch <nat@apn.org>
* rcs2log: Ignore log messages that start with `#'.
@medbreak
You can then edit the new change log entry further as you wish.
Normally, the log entry for file `foo' is displayed as `* foo: text of log entry'. The `:' after `foo' is omitted if the text of the log entry starts with `(functionname): '. For example, if the log entry for `vc.el' is `(vc-do-command): Check call-process status.', then the text in `ChangeLog' looks like this:
@medbreak
Wed May 6 10:53:00 1992 Nathaniel Bowditch <nat@apn.org>
* vc.el (vc-do-command): Check call-process status.
@medbreak
When C-x v a adds several change log entries at once, it groups related log entries together if they all are checked in by the same author at nearly the same time. If the log entries for several such files all have the same text, it coalesces them into a single entry. For example, suppose the most recent checkins have the following log entries:
* For `vc.texinfo': `Fix expansion typos.' * For `vc.el': `Don't call expand-file-name.' * For `vc-hooks.el': `Don't call expand-file-name.'
They appear like this in `ChangeLog':
@medbreak
Wed Apr 1 08:57:59 1992 Nathaniel Bowditch <nat@apn.org>
* vc.texinfo: Fix expansion typos.
* vc.el, vc-hooks.el: Don't call expand-file-name.
@medbreak
Normally, C-x v a separates log entries by a blank line, but you can mark several related log entries to be clumped together (without an intervening blank line) by starting the text of each related log entry with a label of the form `{clumpname} '. The label itself is not copied to `ChangeLog'. For example, suppose the log entries are:
* For `vc.texinfo': `{expand} Fix expansion typos.'
* For `vc.el': `{expand} Don't call expand-file-name.'
* For `vc-hooks.el': `{expand} Don't call expand-file-name.'
Then the text in `ChangeLog' looks like this:
@medbreak
Wed Apr 1 08:57:59 1992 Nathaniel Bowditch <nat@apn.org>
* vc.texinfo: Fix expansion typos.
* vc.el, vc-hooks.el: Don't call expand-file-name.
@medbreak
A log entry whose text begins with `#' is not copied to `ChangeLog'. For example, if you merely fix some misspellings in comments, you can log the change with an entry beginning with `#' to avoid putting such trivia into `ChangeLog'.
vc-version-other-window).
You can examine any version of a file by first visiting it, and then
using C-x v ~ version RET
(vc-version-other-window). This puts the text of version
version in a file named `filename.~version~',
then visits it in a separate window.
To compare two versions of a file, use the command C-x v =
(vc-diff). Plain C-x v = compares the current buffer
contents (saving them in the file if necessary) with the last checked-in
version of the file. C-u C-x v =, with a numeric argument, reads a
file name and two version numbers, then compares those versions of the
specified file.
If you supply a directory name instead of the name of a work file, this command compares the two specified versions of all registered files in that directory and its subdirectories. You can also specify a snapshot name (see section Snapshots) instead of one or both version numbers.
You can specify a checked-in version by its number; an empty input specifies the current contents of the work file (which may be different from all the checked-in versions).
This command works by running the diff utility, getting the
options from the variable diff-switches. It displays the output
in a special buffer in another window. Unlike the M-x diff
command, C-x v = does not try to find the changes in the old and
new versions. This is because one or both versions normally do not
exist as files. They exist only in the records of the master file.
See section Comparing Files, for more information about M-x diff.
To view the detailed version control status and history of a file,
type C-x v l (vc-print-log). It displays the history of
changes to the current file, including the text of the log entries. The
output appears in a separate window.
When you are working on a large program, it's often useful to find all
the files that are currently locked, or all the files maintained in
version control at all. You can use C-x v d (vc-directory)
to show all the locked files in or beneath the current directory. This
includes all files that are locked by any user. C-u C-x v d lists
all files in or beneath the current directory that are maintained with
version control.
The list of files is displayed as a buffer that uses an augmented Dired mode. The names of the users locking various files are shown (in parentheses) in place of the owner and group. All the normal Dired commands work in this buffer. Most interactive VC commands work also, and apply to the file name on the current line.
The C-x v v command (vc-next-action), when used in the
augmented Dired buffer, operates on all the marked files (or the file on
the current line). If it operates on more than one file, it handles
each file according to its current state; thus, it may check out one
file and check in another (because it is already checked out). If it
has to check in any files, it reads a single log entry, then uses that
text for all the files being checked in. This can be convenient for
registering or checking in several files at once, as part of the same
change.
When you rename a registered file, you must also rename its master
file correspondingly to get proper results. Use vc-rename-file
to rename the source file as you specify, and rename its master file
accordingly. It also updates any snapshots (see section Snapshots) that
mention the file, so that they use the new name; despite this, the
snapshot thus modified may not completely work (see section Snapshot Caveats).
You cannot use vc-rename-file on a file that is locked by
someone else.
A snapshot is a named set of file versions (one for each registered file) that you can treat as a unit. One important kind of snapshot is a release, a (theoretically) stable version of the system that is ready for distribution to users.
There are two basic commands for snapshots; one makes a snapshot with a given name, the other retrieves a named snapshot.
C-x v s name RET
vc-create-snapshot).
C-x v r name RET
vc-retrieve-snapshot).
This command reports an error if any files are locked at or below the
current directory, without changing anything; this is to avoid
overwriting work in progress.
A snapshot uses a very small amount of resources--just enough to record the list of file names and which version belongs to the snapshot. Thus, you need not hesitate to create snapshots whenever they are useful.
You can give a snapshot name as an argument to C-x v = or C-x v ~ (see section Examining And Comparing Old Versions). Thus, you can use it to compare a snapshot against the current files, or two snapshots against each other, or a snapshot against a named version.
VC's snapshot facilities are modeled on RCS's named-configuration support. They use RCS's native facilities for this, so under VC snapshots made using RCS are visible even when you bypass VC.
For SCCS, VC implements snapshots itself. The files it uses contain name/file/version-number triples. These snapshots are visible only through VC.
A snapshot is a set of checked-in versions. So make sure that all the files are checked in and not locked when you make a snapshot.
File renaming and deletion can create some difficulties with snapshots. This is not a VC-specific problem, but a general design issue in version control systems that no one has solved very well yet.
If you rename a registered file, you need to rename its master along
with it (the command vc-rename-file does this automatically). If
you are using SCCS, you must also update the records of the snapshot, to
mention the file by its new name (vc-rename-file does this,
too). An old snapshot that refers to a master file that no longer
exists under the recorded name is invalid; VC can no longer retrieve
it. It would be beyond the scope of this manual to explain enough about
RCS and SCCS to explain how to update the snapshots by hand.
Using vc-rename-file makes the snapshot remain valid for
retrieval, but it does not solve all problems. For example, some of the
files in the program probably refer to others by name. At the very
least, the makefile probably mentions the file that you renamed. If you
retrieve an old snapshot, the renamed file is retrieved under its new
name, which is not the name that the makefile expects. So the program
won't really work as retrieved.
Sometimes it is convenient to put version identification strings directly into working files. Certain special strings called version headers are replaced in each successive version by the number of that version.
You can use the C-x v h command (vc-insert-headers) to
insert a suitable header string.
The default header string is `$Id$' for RCS and `%W%' for
SCCS. You can specify other headers to insert by setting the variable
vc-header-alist. Its value is a list of elements of the form
(program . string) where program is RCS
or SCCS and string is the string to use.
Instead of a single string, you can specify a list of strings; then each string in the list is inserted as a separate header on a line of its own.
It is often necessary to use "superfluous" backslashes when writing the strings that you put in this variable. This is to prevent the string in the constant from being interpreted as a header itself if the Emacs Lisp file containing it is maintained with version control.
Each header is inserted surrounded by tabs, inside comment delimiters,
on a new line at the start of the buffer. Normally the ordinary comment
start and comment end strings of the current mode are used, but for
certain modes, there are special comment delimiters for this purpose;
the variable vc-comment-alist specifies them. Each element of
this list has the form (mode starter ender).
The variable vc-static-header-alist specifies further strings
to add based on the name of the buffer. Its value should be a list of
elements of the form (regexp . format). Whenever
regexp matches the buffer name, format is inserted as part
of the header. A header line is inserted for each element that matches
the buffer name, and for each string specified by
vc-header-alist. The header line is made by processing the
string from vc-header-alist with the format taken from the
element. The default value for vc-static-header-alist is as follows:
(("\\.c$" .
"\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\
#endif /* lint */\n"))
It specifies insertion of text of this form:
#ifndef lint static char vcid[] = "string"; #endif /* lint */
Note that the text above starts with a blank line.
If you use more than one version header in a file, put them close
together in the file. The mechanism in revert-buffer that
preserves markers may fail for markers positioned between two version
headers.
The file system groups files into directories. A directory listing is a list of all the files in a directory. Emacs provides directory listings in brief format (file names only) and verbose format (sizes, dates, and authors included). (There is also a directory browser called Dired; section Dired, the Directory Editor.)
list-directory).
The command to display a directory listing is C-x C-d
(list-directory). It reads using the minibuffer a file name
which is either a directory to be listed or a wildcard-containing
pattern for the files to be listed. For example,
C-x C-d /u2/emacs/etc RET
lists all the files in directory `/u2/emacs/etc'. Here is an example of specifying a file name pattern:
C-x C-d /u2/emacs/src/*.c RET
Normally, C-x C-d prints a brief directory listing containing just file names. A numeric argument (regardless of value) tells it to print a verbose listing (like `ls -l').
The text of a directory listing is obtained by running ls in an
inferior process. Two Emacs variables control the switches passed to
ls: list-directory-brief-switches is a string giving the
switches to use in brief listings ("-CF" by default), and
list-directory-verbose-switches is a string giving the switches to
use in a verbose listing ("-l" by default).
The command M-x diff compares two files, displaying the
differences in an Emacs buffer named `*Diff*'. It works by running
the diff program, using options taken from the variable
diff-switches, whose value should be a string.
The buffer `*Diff*' has Compilation mode as its major mode, so you can use C-x ` to visit successive changed locations in the two source files. You can also move to a particular hunk of changes and type C-c C-c, or click Mouse-2 on it, to move to the corresponding source location. You can also use the other special commands of Compilation mode: SPC and DEL for scrolling, and M-p and M-n for cursor motion. See section Running Compilations under Emacs.
The command M-x diff-backup compares a specified file with its most
recent backup. If you specify the name of a backup file,
diff-backup compares it with the source file that it is a backup
of.
The command M-x compare-windows compares the text in the current window with that in the next window. Comparison starts at point in each window. Point moves forward in each window, a character at a time in each window, until the next characters in the two windows are different. Then the command is finished. For more information about windows in Emacs, section Multiple Windows.
With a numeric argument, compare-windows ignores changes in
whitespace. If the variable compare-ignore-case is
non-nil, it ignores differences in case as well.
See also section Merging Files with Emerge, for convenient facilities for merging two similar files.
Emacs has commands for performing many other operations on files. All operate on one file; they do not accept wild card file names.
M-x view-file allows you to scan or read a file by sequential
screenfuls. It reads a file name argument using the minibuffer. After
reading the file into an Emacs buffer, view-file displays the
beginning. You can then type SPC to scroll forward one windowful,
or DEL to scroll backward. Various other commands are provided
for moving around in the file, but none for changing it; type C-h
while viewing for a list of them. They are mostly the same as normal
Emacs cursor motion commands. To exit from viewing, type C-c.
The commands for viewing are defined by a special major mode called View
mode.
A related command, M-x view-buffer, views a buffer already present in Emacs. See section Miscellaneous Buffer Operations.
M-x insert-file inserts a copy of the contents of the specified file into the current buffer at point, leaving point unchanged before the contents and the mark after them.
M-x write-region is the inverse of M-x insert-file; it copies the contents of the region into the specified file. M-x append-to-file adds the text of the region to the end of the specified file. See section Accumulating Text.
M-x delete-file deletes the specified file, like the rm
command in the shell. If you are deleting many files in one directory, it
may be more convenient to use Dired (see section Dired, the Directory Editor).
M-x rename-file reads two file names old and new using the minibuffer, then renames file old as new. If a file named new already exists, you must confirm with yes or renaming is not done; this is because renaming causes the old meaning of the name new to be lost. If old and new are on different file systems, the file old is copied and deleted.
The similar command M-x add-name-to-file is used to add an additional name to an existing file without removing its old name. The new name must belong on the same file system that the file is on.
M-x copy-file reads the file old and writes a new file named new with the same contents. Confirmation is required if a file named new already exists, because copying has the consequence of overwriting the old contents of the file new.
M-x make-symbolic-link reads two file names old and linkname, then creates a symbolic link named linkname and pointing at old. The effect is that future attempts to open file linkname will refer to whatever file is named old at the time the opening is done, or will get an error if the name old is not in use at that time. This command does not expand the argument filename, so that it allows you to specify a relative name as the target of the link.
Confirmation is required when creating the link if linkname is in use. Note that not all systems support symbolic links.
The text you are editing in Emacs resides in an object called a buffer. Each time you visit a file, a buffer is created to hold the file's text. Each time you invoke Dired, a buffer is created to hold the directory listing. If you send a message with C-x m, a buffer named `*mail*' is used to hold the text of the message. When you ask for a command's documentation, that appears in a buffer called `*Help*'.
At any time, one and only one buffer is selected. It is also called the current buffer. Often we say that a command operates on "the buffer" as if there were only one; but really this means that the command operates on the selected buffer (most commands do).
When Emacs has multiple windows, each window has a chosen buffer which is displayed there, but at any time only one of the windows is selected and its chosen buffer is the selected buffer. Each window's mode line displays the name of the buffer that the window is displaying (see section Multiple Windows).
Each buffer has a name, which can be of any length, and you can select any buffer by giving its name. Most buffers are made by visiting files, and their names are derived from the files' names. But you can also create an empty buffer with any name you want. A newly started Emacs has a buffer named `*scratch*' which can be used for evaluating Lisp expressions in Emacs. The distinction between upper and lower case matters in buffer names.
Each buffer records individually what file it is visiting, whether it is modified, and what major mode and minor modes are in effect in it (see section Major Modes). Any Emacs variable can be made local to a particular buffer, meaning its value in that buffer can be different from the value in other buffers. See section Local Variables.
switch-to-buffer).
switch-to-buffer-other-window).
switch-to-buffer-other-frame).
To select the buffer named bufname, type C-x b bufname
RET. This runs the command switch-to-buffer with argument
bufname. You can use completion on an abbreviation for the buffer
name you want (see section Completion). An empty argument to C-x b
specifies the most recently selected buffer that is not displayed in any
window.
Most buffers are created by visiting files, or by Emacs commands that
want to display some text, but you can also create a buffer explicitly by
typing C-x b bufname RET. This makes a new, empty buffer which
is not visiting any file, and selects it for editing. Such buffers are
used for making notes to yourself. If you try to save one, you are asked
for the file name to use. The new buffer's major mode is determined by the
value of default-major-mode (see section Major Modes).
Note that C-x C-f, and any other command for visiting a file, can also be used to switch to an existing file-visiting buffer. See section Visiting Files.
list-buffers).
To print a list of all the buffers that exist, type C-x C-b. Each line in the list shows one buffer's name, major mode and visited file. The buffers are listed in the order, most recently visited first.
`*' at the beginning of a line indicates the buffer is "modified". If several buffers are modified, it may be time to save some with C-x s (see section Saving Files). `%' indicates a read-only buffer. `.' marks the selected buffer. Here is an example of a buffer list:
MR Buffer Size Mode File
-- ------ ---- ---- ----
.* emacs.tex 383402 Texinfo /u2/emacs/man/emacs.tex
*Help* 1287 Fundamental
files.el 23076 Emacs-Lisp /u2/emacs/lisp/files.el
% RMAIL 64042 RMAIL /u/rms/RMAIL
*% man 747 Dired /u2/emacs/man/
net.emacs 343885 Fundamental /u/rms/net.emacs
fileio.c 27691 C /u2/emacs/src/fileio.c
NEWS 67340 Text /u2/emacs/etc/NEWS
*scratch* 0 Lisp Interaction
Note that the buffer `*Help*' was made by a help request; it is not
visiting any file. The buffer man was made by Dired on the
directory `/u2/emacs/man/'.
vc-toggle-read-only).
A buffer can be read-only, which means that commands to change its contents are not allowed. The mode line indicates read-only buffers with `%%' or `%*' near the left margin. Read-only buffers are usually made by subsystems such as Dired and Rmail that have special commands to operate on the text; also by visiting a file whose access control says you cannot write it.
If you wish to make changes in a read-only buffer, use the command
C-x C-q (vc-toggle-read-only). It makes a read-only buffer
writable, and makes a writable buffer read-only. In most cases, this
works by setting the variable buffer-read-only, which has a local
value in each buffer and makes the buffer read-only if its value is
non-nil. If the file is maintained with version control,
C-x C-q works through the version control system to change the
read-only status of the file as well as the buffer.
M-x rename-buffer changes the name of the current buffer. Specify the new name as a minibuffer argument. There is no default. If you specify a name that is in use for some other buffer, an error happens and no renaming is done.
M-x rename-uniquely renames the current buffer to a similar name with a numeric suffix added to make it both different and unique. This command does not need an argument. It is useful for creating multiple shell buffers: if you rename the `*Shell*' buffer, then do M-x shell again, it makes a new shell buffer named `*Shell*'; meanwhile, the old shell buffer continues to exist under its new name. This method is also good for mail buffers, compilation buffers, and most Emacs features that create special buffers with particular names.
M-x view-buffer is much like M-x view-file (see section Miscellaneous File Operations) except that it examines an already existing Emacs buffer. View mode provides commands for scrolling through the buffer conveniently but not for changing it. When you exit View mode, the value of point that resulted from your perusal remains in effect.
The commands M-x append-to-buffer and M-x insert-buffer can be used to copy text from one buffer to another. See section Accumulating Text.
If you continue an Emacs session for a while, you may accumulate a large number of buffers. You may then find it convenient to kill the buffers you no longer need. On most operating systems, killing a buffer releases its space back to the operating system so that other programs can use it. Here are some commands for killing buffers:
kill-buffer).
C-x k (kill-buffer) kills one buffer, whose name you
specify in the minibuffer. The default, used if you type just RET
in the minibuffer, is to kill the current buffer. If you kill the
current buffer, another buffer is selected; one that has been selected
recently but does not appear in any window now. If you ask to kill a
file-visiting buffer that is modified (has unsaved editing), then you
must confirm with yes before the buffer is killed.
The command M-x kill-some-buffers asks about each buffer, one by
one. An answer of y means to kill the buffer. Killing the current
buffer or a buffer containing unsaved changes selects a new buffer or asks
for confirmation just like kill-buffer.
The buffer menu feature (see section Operating on Several Buffers) is also convenient for killing various buffers.
If you want to do something special every time a buffer is killed, you
can add hook functions to the hook kill-buffer-hook (see section Hooks).
The buffer-menu facility is like a "Dired for buffers"; it allows you to request operations on various Emacs buffers by editing an Emacs buffer containing a list of them. You can save buffers, kill them (here called deleting them, for consistency with Dired), or display them.
The command buffer-menu writes a list of all Emacs buffers into
the buffer `*Buffer List*', and selects that buffer in Buffer Menu
mode. The buffer is read-only, and can be changed only through the
special commands described in this section. The usual Emacs cursor
motion commands can be used in the `*Buffer List*' buffer. The
following commands apply to the buffer described on the current line.
The d, s and u commands to add or remove flags also move down a line. They accept a numeric argument as a repeat count.
These commands operate immediately on the buffer listed on the current line:
There are also commands to select another buffer or buffers:
All that buffer-menu does directly is create and select a suitable
buffer, and turn on Buffer Menu mode. Everything else described above is
implemented by the special commands provided in Buffer Menu mode. One
consequence of this is that you can switch from the `*Buffer List*'
buffer to another Emacs buffer, and edit there. You can reselect the
buffer-menu buffer later, to perform the operations already
requested, or you can kill it, or pay no further attention to it.
The only difference between buffer-menu and list-buffers is
that buffer-menu selects the `*Buffer List*' buffer and
list-buffers does not. If you run list-buffers (that is,
type C-x C-b) and select the buffer list manually, you can use all of
the commands described here.
The buffer `*Buffer List*' is not updated automatically when
buffers are created and killed; its contents are just text. If you have
created, deleted or renamed buffers, the way to update `*Buffer
List*' to show what you have done is to type g
(revert-buffer) or repeat the buffer-menu command.
Emacs can split a frame into two or many windows. Multiple windows can display parts of different buffers, or different parts of one buffer. Multiple frames always imply multiple windows, because each frame has its own set of windows. Each window belongs to one and only one frame.
Each Emacs window displays one Emacs buffer at any time. A single buffer may appear in more than one window; if it does, any changes in its text are displayed in all the windows where it appears. But the windows showing the same buffer can show different parts of it, because each window has its own value of point.
At any time, one of the windows is the selected window; the buffer this window is displaying is the current buffer. The terminal's cursor shows the location of point in this window. Each other window has a location of point as well, but since the terminal has only one cursor there is no way to show where those locations are. When you make multiple frames, each frame has a cursor which appears in the frame's selected window. The cursor in the selected frame is solid; the cursor in other frames is a hollow box.
Commands to move point affect the value of point for the selected Emacs
window only. They do not change the value of point in any other Emacs
window, even one showing the same buffer. The same is true for commands
such as C-x b to change the selected buffer in the selected window;
they do not affect other windows at all. However, there are other commands
such as C-x 4 b that select a different window and switch buffers in
it. Also, all commands that display information in a window, including
(for example) C-h f (describe-function) and C-x C-b
(list-buffers), work by switching buffers in a nonselected window
without affecting the selected window.
When multiple windows show the same buffer, they can have different regions, because they can have different values of point. This means that in Transient Mark mode, each window highlights a different part of the buffer. The part that is highlighted in the selected window is the region that editing commands use.
Each window has its own mode line, which displays the buffer name, modification status and major and minor modes of the buffer that is displayed in the window. See section The Mode Line, for full details on the mode line.
@break
split-window-vertically).
split-window-horizontally).
The command C-x 2 (split-window-vertically) breaks the
selected window into two windows, one above the other. Both windows start
out displaying the same buffer, with the same value of point. By default
the two windows each get half the height of the window that was split; a
numeric argument specifies how many lines to give to the top window.
C-x 3 (split-window-horizontally) breaks the selected
window into two side-by-side windows. A numeric argument specifies
how many columns to give the one on the left. A line of vertical bars
separates the two windows. Windows that are not the full width of the
screen have mode lines, but they are truncated; also, they do not
always appear in inverse video, because the Emacs display routines
have not been taught how to display a region of inverse video that is
only part of a line on the screen.
You can split a window horizontally or vertically by clicking C-Mouse-2 in the mode line or the scroll bar. The line of splitting goes through the place where you click: if you click on the mode line, the new scroll bar goes above the spot; if you click in the scroll bar, the mode line of the split window is side by side with your click.
When a window is less than the full width, text lines too long to fit are
frequent. Continuing all those lines might be confusing. The variable
truncate-partial-width-windows can be set non-nil to force
truncation in all windows less than the full width of the screen,
independent of the buffer being displayed and its value for
truncate-lines. See section Continuation Lines.
Horizontal scrolling is often used in side-by-side windows. See section Controlling the Display.
If split-window-keep-point is non-nil, C-x 2 tries to
avoid shifting any text on the screen by putting point in whichever
window happens to contain the screen line the cursor is already on. The
default is that split-window-keep-point is non-nil on slow
terminals.
other-window). That is o, not zero.
scroll-other-window).
mouse-select-region).
To select a different window, click with Mouse-1 on its mode
line. With the keyboard, you can switch windows by typing C-x o
(other-window). That is an o, for `other', not a zero.
When there are more than two windows, this command moves through all the
windows in a cyclic order, generally top to bottom and left to right.
After the rightmost and bottommost window, it goes back to the one at
the upper left corner. A numeric argument means to move several steps
in the cyclic order of windows. A negative argument moves around the
cycle in the opposite order. When the minibuffer is active, the
minibuffer is the last window in the cycle; you can switch from the
minibuffer window to one of the other windows, and later switch back and
finish supplying the minibuffer argument that is requested.
See section Editing in the Minibuffer.
The usual scrolling commands (see section Controlling the Display) apply to the selected
window only, but there is one command to scroll the next window.
C-M-v (scroll-other-window) scrolls the window that
C-x o would select. It takes arguments, positive and negative,
like C-v. (In the minibuffer, C-M-v scrolls the window
that contains the minibuffer help display, if any, rather than the
next window in the standard cyclic order.)
The command M-x compare-windows lets you compare two files or
buffers visible in two windows, by moving through them to the next
mismatch. See section Comparing Files, for details.
C-x 4 is a prefix key for commands that select another window (splitting the window if there is only one) and select a buffer in that window. Different C-x 4 commands have different ways of finding the buffer to select.
switch-to-buffer-other-window.
display-buffer.
find-file-other-window. See section Visiting Files.
dired-other-window. See section Dired, the Directory Editor.
mail-other-window; its same-window analogue is C-x m
(see section Sending Mail).
find-tag-other-window, the multiple-window variant of M-.
(see section Tags Tables).
find-file-read-only-other-window.
See section Visiting Files.
delete-window). That is a zero.
delete-other-windows).
enlarge-window).
enlarge-window-horizontally).
mouse-delete-other-windows).
mouse-delete-window).
To delete a window, type C-x 0 (delete-window). (That is
a zero.) The space occupied by the deleted window is given to an
adjacent window (but not the minibuffer window, even if that is active
at the time). Once a window is deleted, its attributes are forgotten;
only restoring a window configuration can bring it back. Deleting the
window has no effect on the buffer it used to display; the buffer
continues to exist, and you can select it in any window with C-x
b.
C-x 1 (delete-other-windows) is more powerful than
C-x 0; it deletes all the windows except the selected one (and the
minibuffer); the selected window expands to use the whole frame except
for the echo area.
You can also delete a window by clicking on its mode line with Mouse-2, and expand a window to full screen by clicking on its mode line with Mouse-3.
To readjust the division of space among vertically adjacent windows,
use C-x ^ (enlarge-window). It makes the currently
selected window get one line bigger, or as many lines as is specified
with a numeric argument. With a negative argument, it makes the
selected window smaller. C-x }
(enlarge-window-horizontally) makes the selected window wider by
the specified number of columns. The extra screen space given to a
window comes from one of its neighbors, if that is possible. If this
makes any window too small, it is deleted and its space is given to an
adjacent window. The minimum size is specified by the variables
window-min-height and window-min-width.
See section Editing in the Minibuffer, for information about the Resize-Minibuffer mode, which automatically changes the size of the minibuffer window to fit the text in the minibuffer.
When using the X Window System, you can create multiple windows at the X level in a single Emacs session. Each X window that belongs to Emacs displays a frame which can contain one or several Emacs windows. A frame initially contains a single general-purpose Emacs window which you can subdivide vertically or horizontally into smaller windows. A frame normally contains its own echo area and minibuffer, but you can make frames that don't have these--they use the echo area and minibuffer of another frame.
Editing you do in one frame also affects the other frames. For instance, if you put text in the kill ring in one frame, you can yank it in another frame. If you exit Emacs through C-x C-c in one frame, it terminates all the frames. To delete just one frame, use C-x 5 0.
To avoid confusion, we reserve the word "window" for the subdivisions that Emacs implements, and never use it to refer to a frame.
The mouse commands for selecting and copying a region are mostly
compatible with the xterm program. You can use the same mouse
commands for copying between Emacs and other X client programs.
mouse-set-point).
This is normally the left button.
mouse-set-region). You can specify both ends of
the region with this single command.
If you move the mouse off the top or bottom of the window while
dragging, the window scrolls at a steady rate until you move the mouse
back into the window. This way, you can select regions that don't fit
entirely on the screen.
mouse-yank-at-click).
This is normally the middle button.
mouse-save-then-kill, has several functions
depending on where you click and the status of the region.
If you have a highlighted region, or if the region was set just before
by dragging button 1, Mouse-3 adjusts the nearer end of the region
by moving it to where you click. The adjusted region's text also
replaces the old region's text in the kill ring.
Otherwise, Mouse-3 sets mark where you click, without changing
point. It copies the new region to the kill ring.
If you originally specified the region using a double or triple
Mouse-1, so that the region is defined to consist of entire words
or lines, then adjusting the region also proceeds by entire words or
lines.
If you use Mouse-3 twice in a row at the same place,
that kills the region already selected.
The simplest way to kill text with the mouse is to press Mouse-1 at one end, then press Mouse-3 twice at the other end. See section Deletion and Killing. To copy the text into the kill ring without deleting it from the buffer, press Mouse-3 just once--or just drag across the text with Mouse-1. Then you can copy it elsewhere by yanking it.
To yank the killed or copied text somewhere else, move the mouse there
and press Mouse-2. See section Yanking. However, if
mouse-yank-at-point is non-nil, Mouse-2 yanks at
point. Then it does not matter precisely where you click; all that
matters is which window you click on. The default value is nil.
This variable also effects yanking the secondary selection.
To copy text to another X window, kill it or save it in the kill ring. Under X, this also sets the primary selection. Then use the "paste" or "yank" command of the program operating the other window to insert the text from the selection.
To copy text from another X window, use the "cut" or "copy" command of the program operating the other window, to select the text you want. Then yank it in Emacs with C-y or Mouse-2.
When Emacs puts text into the kill ring, or rotates text to the front
of the kill ring, it sets the primary selection in the X server.
This is how other X clients can access the text. Emacs also stores the
text in the cut buffer, but only if the text is short enough
(x-cut-buffer-max specifies the maximum number of characters);
putting long strings in the cut buffer can be slow.
The commands to yank the first entry in the kill ring actually check first for a primary selection in another program; after that, they check for text in the cut buffer. If neither of those sources provides text to yank, the kill ring contents are used.
The secondary selection is another way of selecting text using X. It does not use point or the mark, so you can use it to kill text without setting point or the mark.
mouse-set-secondary). The highlighting appears and changes as
you drag.
If you move the mouse off the top or bottom of the window while
dragging, the window scrolls at a steady rate until you move the mouse
back into the window. This way, you can mark regions that don't fit
entirely on the screen.
mouse-start-secondary).
mouse-secondary-save-then-kill). A second click
at the same place kills the secondary selection just made.
mouse-kill-secondary). This places point at the end of the
yanked text.
Double or triple clicking of M-Mouse-1 operates on words and lines, much like Mouse-1.
If mouse-yank-at-point is non-nil, M-Mouse-2
yanks at point. Then it does not matter precisely where you click; all
that matters is which window you click on. See section Mouse Commands.
Some Emacs buffers display lists of various sorts. These include lists of files, of buffers, of possible completions, of matches for a pattern, and so on.
Since yanking text into these buffers is not very useful, most of them define Mouse-2 specially, as a command to use or view the item you click on.
For example, if you click Mouse-2 on a file name in a Dired buffer, you visit the that file. If you click Mouse-2 on an error message in the `*Compilation*' buffer, you go to the source code for that error message. If you click Mouse-2 on a completion in the `*Completions*' buffer, you choose that completion.
You can usually tell when Mouse-2 has this special sort of meaning because the sensitive text highlights when you move the mouse over it.
You can use mouse clicks on window mode lines to select and manipulate windows.
C-Mouse-2 on a scroll bar splits the corresponding window vertically. See section Splitting Windows.
The prefix key C-x 5 is analogous to C-x 4, with parallel subcommands. The difference is that C-x 5 commands create a new frame rather than just a new window in the selected frame (See section Displaying in Another Window). If an existing visible or iconified frame already displays the requested material, these commands use the existing frame, after raising or deiconifying as necessary.
The various C-x 5 commands differ in how they find or create the buffer to select:
make-frame).
switch-to-buffer-other-frame.
find-file-other-frame. See section Visiting Files.
dired-other-frame. See section Dired, the Directory Editor.
mail-other-frame. It is the other-frame variant of C-x m.
See section Sending Mail.
find-tag-other-frame, the multiple-frame variant of M-..
See section Tags Tables.
find-file-read-only-other-frame.
See section Visiting Files.
You can control the appearance of new frames you create by setting the
frame parameters in default-frame-alist. You can use the
variable initial-frame-alist to specify parameters that affect
only the initial frame. See section `Initial Parameters' in The Emacs Lisp Manual, for more information.
You can make certain chosen buffers, for which Emacs normally creates
a second window when you have just one window, appear in special frames
of their own. To do this, set the variable
special-display-buffer-names to a list of buffer names; any
buffer whose name is in that list automatically gets a special frame
when it is to be displayed in another window.
For example, if you set the variable this way,
(setq special-display-buffer-names
'("*Completions*" "*grep*" "*tex-shell*"))
then completion lists, grep output and the TeX mode shell
buffer get individual frames of their own. These frames, and the
windows in them, are never automatically split or reused for any other
buffers. They continue to show the buffers they were created for,
unless you alter them by hand. Killing the special buffer deletes its
frame automatically.
More generally, you can set special-display-regexps to a list
of regular expressions; then a buffer gets its own frame if its name
matches any of those regular expressions. (Once again, this applies only
to buffers that normally get displayed for you in a separate window.)
The variable special-display-frame-alist specifies the frame
parameters for these frames. It has a default value, so you don't need
to set it.
This section describes commands for altering the display style and window management behavior of the selected frame.
auto-raise-mode has no effect on
it.
auto-lower-mode has no effect on auto-lower
implemented by the X window manager. To control that, you must use
the appropriate window manager features.
In Emacs versions that use an X toolkit, the color-setting and font-setting functions don't affect menus and the menu bar, since they are displayed by their own widget classes. To change the appearance of the menus and menu bar, you must use X resources (see section X Resources). See section Window Color Options, regarding colors. See section Font Specification Options, regarding choice of font.
For information on frame parameters and customization, see section `Frame Parameters' in The Emacs Lisp Manual.
When using X, Emacs normally makes a scroll bar at the right of each Emacs window. The scroll bar runs the height of the window, and shows a moving rectangular inner box which represents the portion of the buffer currently displayed. The entire height of the scroll bar represents the entire length of the buffer.
You can use Mouse-2 (normally, the middle button) in the scroll bar to move or drag the inner box up and down. If you move it to the top of the scroll bar, you see the top of the buffer. If you move it to the bottom of the scroll bar, you see the bottom of the buffer.
The left and right buttons in the scroll bar scroll by controlled increments. Mouse-1 (normally, the left button) moves the line at the level where you click up to the top of the window. Mouse-3 (normally, the right button) moves the line at the top of the window down to the level where you click. By clicking repeatedly in the same place, you can scroll by the same distance over and over.
Aside from scrolling, you can also click C-Mouse-2 in the scroll bar to split a window vertically. The split occurs on the line where you click.
You can enable or disable Scroll Bar mode with the command M-x scroll-bar-mode. With no argument, it toggles the use of scroll bars. With an argument, it turns use of scroll bars on if and only if the argument is positive. This command applies to all frames, including frames yet to be created.
To enable or disable scroll bars for just the selected frame, use the M-x toggle-scroll-bar command.
By default, each Emacs frame has a menu bar at the top which you can use to perform certain common operations. There's no need to describe them in detail here, as you can more easily see for yourself; also, we may change them and add to them in subsequent Emacs versions.
Each of the operations in the menu bar is bound to an ordinary Emacs command which you can invoke equally well with M-x or with its own key bindings. The menu lists one equivalent key binding (if the command has any) at the right margin. To see the command's name and documentation, type C-h k and then select the menu bar item you are interested in.
You can turn display of menu bars on or off with M-x menu-bar-mode. With no argument, this command toggles Menu Bar mode, a minor mode. With an argument, the command turns Menu Bar mode on if the argument is positive, off if the argument is not positive.
When using Emacs with X, you can set up multiple styles of displaying characters. The aspects of style that you can control are the type font, the foreground color, the background color, and whether to underline. Emacs 19.26 does not support faces on MS-DOS, but future versions will support them partially (see section MS-DOS Issues).
The way you control display style is by defining named faces. Each face can specify a type font, a foreground color, a background color, and an underline flag; but it does not have to specify all of them.
The style of display used for a given character in the text is determined by combining several faces. Which faces to use is always set up by Lisp programs, at present, by means of text properties and overlays. Any aspect of the display style that isn't specified by overlays or text properties comes from the frame itself.
To see what faces are currently defined, and what they look like, type M-x list-faces-display. It's possible for a given face to look different in different frames; this command shows the appearance in the frame in which you type it. Here's a list of the standardly defined faces:
default
modeline
highlight
region
secondary-selection
bold
italic
bold-italic
underline
When Transient Mark mode is enabled, the text of the region is
highlighted when the mark is active. This uses the face named
region; you can control the style of highlighting by changing the
style of this face (see section Modifying Faces). See section Transient Mark Mode,
for more information about Transient Mark mode and activation and
deactivation of the mark.
One easy way to use faces is to turn on Font-Lock mode. This minor mode, which is always local to a particular buffer, arranges to choose faces according to the syntax of the text you are editing. It can recognize comments and strings in any major mode; for several major modes, it can also recognize and properly highlight various other important parts of the text. To get the full benefit of Font-Lock mode, you need to choose a default font which has bold, italic, and bold-italic variants.
Here are the commands users can use to change the font of a face:
Here are the commands for setting the colors and underline flag of a face:
You can also use X resources to specify attributes of particular faces. See section X Resources.
The following commands do user-level management of frames under a window system:
iconify-or-deiconify-frame). The normal meaning of C-z,
to suspend Emacs, is not useful under a window system, so it has a
different binding in that case.
If you type this command on an Emacs frame's icon, it deiconifies the frame.
delete-frame).
This is not allowed if there is only one frame.
Emacs provides many alternative major modes, each of which customizes Emacs for editing text of a particular sort. The major modes are mutually exclusive, and each buffer has one major mode at any time. The mode line normally shows the name of the current major mode, in parentheses (see section The Mode Line).
The least specialized major mode is called Fundamental mode. This mode has no mode-specific redefinitions or variable settings, so that each Emacs command behaves in its most general manner, and each option is in its default state. For editing text of a specific type that Emacs knows about, such as Lisp code or English text, you should switch to the appropriate major mode, such as Lisp mode or Text mode.
Selecting a major mode changes the meanings of a few keys to become more specifically adapted to the language being edited. The ones which are changed frequently are TAB, DEL, and LFD. The prefix key C-c normally contains mode-specific commands. In addition, the commands which handle comments use the mode to determine how comments are to be delimited. Many major modes redefine the syntactical properties of characters appearing in the buffer. See section The Syntax Table.
The major modes fall into three major groups. Lisp mode (which has several variants), C mode, Fortran mode and others are for specific programming languages. Text mode, Nroff mode, TeX mode and Outline mode are for editing English text. The remaining major modes are not intended for use on users' files; they are used in buffers created for specific purposes by Emacs, such as Dired mode for buffers made by Dired (see section Dired, the Directory Editor), and Mail mode for buffers made by C-x m (see section Sending Mail), and Shell mode for buffers used for communicating with an inferior shell process (see section Interactive Inferior Shell).
Most programming language major modes specify that only blank lines separate paragraphs. This is to make the paragraph commands useful. (See section Paragraphs.) They also cause Auto Fill mode to use the definition of TAB to indent the new lines it creates. This is because most lines in a program are usually indented. (See section Indentation.)
You can select a major mode explicitly for the current buffer, but most of the time Emacs determines which mode to use based on the file name or on special text in the file.
Explicit selection of a new major mode is done with a M-x command.
From the name of a major mode, add -mode to get the name of a
command to select that mode. Thus, you can enter Lisp mode by executing
M-x lisp-mode.
When you visit a file, Emacs usually chooses the right major mode based
on the file's name. For example, files whose names end in `.c' are
edited in C mode. The correspondence between file names and major mode is
controlled by the variable auto-mode-alist. Its value is a list in
which each element has the form
(regexp . mode-function)
For example, one element normally found in the list has the form
("\\.c\\'" . c-mode), and it is responsible for selecting C mode
for files whose names end in `.c'. (Note that `\\' is needed in
Lisp syntax to include a `\' in the string, which is needed to
suppress the special meaning of `.' in regexps.) The only practical
way to change this variable is with Lisp code.
You can specify which major mode should be used for editing a certain file by a special sort of text in the first nonblank line of the file. The mode name should appear in this line both preceded and followed by `-*-'. Other text may appear on the line as well. For example,
;-*-Lisp-*-
tells Emacs to use Lisp mode. Such an explicit specification overrides any defaulting based on the file name. Note how the semicolon is used to make Lisp treat this line as a comment.
Another format of mode specification is
-*-Mode: modename;-*-
which allows you to specify local variables as well, like this:
-*- mode: modename; var: value; ... -*-
See section Local Variables in Files, for more information about this.
When you visit a file that does not specify a major mode to use, or
when you create a new buffer with C-x b, the variable
default-major-mode specifies which major mode to use. Normally
its value is the symbol fundamental-mode, which specifies
Fundamental mode. If default-major-mode is nil, the major
mode is taken from the previously selected buffer.
If you change the major mode of a buffer, you can go back to the major
mode Emacs would choose automatically: use the command M-x
normal-mode to do this. This is the same function that
find-file calls to choose the major mode. It also processes
the file's local variables list if any.
This chapter describes the Emacs commands that add, remove, or adjust indentation.
newline-and-indent).
delete-indentation). This would cancel out
the effect of LFD.
split-line).
back-to-indentation).
indent-region).
indent-rigidly).
tab-to-tab-stop).
Most programming languages have some indentation convention. For Lisp code, lines are indented according to their nesting in parentheses. The same general idea is used for C code, though many details are different.
Whatever the language, to indent a line, use the TAB command. Each major mode defines this command to perform the sort of indentation appropriate for the particular language. In Lisp mode, TAB aligns the line according to its depth in parentheses. No matter where in the line you are when you type TAB, it aligns the line as a whole. In C mode, TAB implements a subtle and sophisticated indentation style that knows about many aspects of C syntax.
In Text mode, TAB runs the command tab-to-tab-stop, which
indents to the next tab stop column. You can set the tab stops with
M-x edit-tab-stops.
To move over the indentation on a line, do M-m
(back-to-indentation). This command, given anywhere on a line,
positions point at the first nonblank character on the line.
To insert an indented line before the current line, do C-a C-o TAB. To make an indented line after the current line, use C-e LFD.
If you just want to insert a tab character in the buffer, you can type C-q TAB.
C-M-o (split-line) moves the text from point to the end of
the line vertically down, so that the current line becomes two lines.
C-M-o first moves point forward over any spaces and tabs. Then it
inserts after point a newline and enough indentation to reach the same
column point is on. Point remains before the inserted newline; in this
regard, C-M-o resembles C-o.
To join two lines cleanly, use the M-^
(delete-indentation) command. It deletes the indentation at the
front of the current line, and the line boundary as well, replacing them
with a single space. As a special case (useful for Lisp code) the
single space is omitted if the characters to be joined are consecutive
open parentheses or closing parentheses, or if the junction follows
another newline. To delete just the indentation of a line, go to the
beginning of the line and use M-\
(delete-horizontal-space), which deletes all spaces and tabs
around the cursor.
If you have a fill prefix, M-^ deletes the fill prefix if it appears after the newline that is deleted. See section The Fill Prefix.
There are also commands for changing the indentation of several lines
at once. C-M-\ (indent-region) applies to all the lines
that begin in the region; it indents each line in the "usual" way, as
if you had typed TAB at the beginning of the line. A numeric
argument specifies the column to indent to, and each line is shifted
left or right so that its first nonblank character appears in that
column. C-x TAB (indent-rigidly) moves all of the
lines in the region right by its argument (left, for negative
arguments). The whole group of lines moves rigidly sideways, which is
how the command gets its name.
M-x indent-relative indents at point based on the previous line
(actually, the last nonempty line). It inserts whitespace at point, moving
point, until it is underneath an indentation point in the previous line.
An indentation point is the end of a sequence of whitespace or the end of
the line. If point is farther right than any indentation point in the
previous line, the whitespace before point is deleted and the first
indentation point then applicable is used. If no indentation point is
applicable even then, indent-relative runs tab-to-tab-stop
(see next section).
indent-relative is the definition of TAB in Indented Text
mode. See section Commands for Human Languages.
For typing in tables, you can use Text mode's definition of TAB,
tab-to-tab-stop. This command inserts indentation before point,
enough to reach the next tab stop column. If you are not in Text mode,
this command can be found on the key M-i.
You can specify the tab stops used by M-i. They are stored in a
variable called tab-stop-list, as a list of column-numbers in
increasing order.
The convenient way to set the tab stops is with M-x edit-tab-stops,
which creates and selects a buffer containing a description of the tab stop
settings. You can edit this buffer to specify different tab stops, and
then type C-c C-c to make those new tab stops take effect. In the
tab stop buffer, C-c C-c runs the function
edit-tab-stops-note-changes rather than its usual definition
save-buffer. edit-tab-stops records which buffer was current
when you invoked it, and stores the tab stops back in that buffer; normally
all buffers share the same tab stops and changing them in one buffer
affects all, but if you happen to make tab-stop-list local in one
buffer then edit-tab-stops in that buffer will edit the local
settings.
Here is what the text representing the tab stops looks like for ordinary tab stops every eight columns.
: : : : : :
0 1 2 3 4
0123456789012345678901234567890123456789012345678
To install changes, type C-c C-c
The first line contains a colon at each tab stop. The remaining lines are present just to help you see where the colons are and know what to do.
Note that the tab stops that control tab-to-tab-stop have nothing
to do with displaying tab characters in the buffer. See section Variables Controlling Display,
for more information on that.
Emacs normally uses both tabs and spaces to indent lines. If you prefer,
all indentation can be made from spaces only. To request this, set
indent-tabs-mode to nil. This is a per-buffer variable;
altering the variable affects only the current buffer, but there is a
default value which you can change as well. See section Local Variables.
There are also commands to convert tabs to spaces or vice versa, always preserving the columns of all nonblank text. M-x tabify scans the region for sequences of spaces, and converts sequences of at least three spaces to tabs if that can be done without changing indentation. M-x untabify changes all tabs in the region to appropriate numbers of spaces.
The term text has two widespread meanings in our area of the computer field. One is data that is a sequence of characters. Any file that you edit with Emacs is text, in this sense of the word. The other meaning is more restrictive: a sequence of characters in a human language for humans to read (possibly after processing by a text formatter), as opposed to a program or commands for a program.
Human languages have syntactic/stylistic conventions that can be supported or used to advantage by editor commands: conventions involving words, sentences, paragraphs, and capital letters. This chapter describes Emacs commands for all of these things. There are also commands for filling, which means rearranging the lines of a paragraph to be approximately equal in length. The commands for moving over and killing words, sentences and paragraphs, while intended primarily for editing text, are also often useful for editing programs.
Emacs has several major modes for editing human language text. If the file contains text pure and simple, use Text mode, which customizes Emacs in small ways for the syntactic conventions of text. For text which contains embedded commands for text formatters, Emacs has other major modes, each for a particular text formatter. Thus, for input to TeX, you would use TeX mode; for input to nroff, Nroff mode. Outline mode provides special commands for operating on text with an outline structure.
Emacs has commands for moving over or operating on words. By convention, the keys for them are all Meta characters.
forward-word).
backward-word).
kill-word).
backward-kill-word).
mark-word).
transpose-words).
Notice how these keys form a series that parallels the character-based C-f, C-b, C-d, C-t and DEL. M-@ is cognate to C-@, which is an alias for C-SPC.
The commands M-f (forward-word) and M-b
(backward-word) move forward and backward over words. These
Meta characters are thus analogous to the corresponding control
characters, C-f and C-b, which move over single characters
in the text. The analogy extends to numeric arguments, which serve as
repeat counts. M-f with a negative argument moves backward, and
M-b with a negative argument moves forward. Forward motion
stops right after the last letter of the word, while backward motion
stops right before the first letter.
M-d (kill-word) kills the word after point. To be
precise, it kills everything from point to the place M-f would
move to. Thus, if point is in the middle of a word, M-d kills
just the part after point. If some punctuation comes between point and the
next word, it is killed along with the word. (If you wish to kill only the
next word but not the punctuation before it, simply do M-f to get
the end, and kill the word backwards with M-DEL.)
M-d takes arguments just like M-f.
M-DEL (backward-kill-word) kills the word before
point. It kills everything from point back to where M-b would
move to. If point is after the space in `FOO, BAR', then
`FOO, ' is killed. (If you wish to kill just `FOO', do
M-b M-d instead of M-DEL.)
M-t (transpose-words) exchanges the word before or
containing point with the following word. The delimiter characters between
the words do not move. For example, `FOO, BAR' transposes into
`BAR, FOO' rather than `BAR FOO,'. See section Transposing Text, for
more on transposition and on arguments to transposition commands.
To operate on the next n words with an operation which applies
between point and mark, you can either set the mark at point and then move
over the words, or you can use the command M-@ (mark-word)
which does not move point, but sets the mark where M-f would move
to. M-@ accepts a numeric argument that says how many words to
scan for the place to put the mark. In Transient Mark mode, this command
activates the mark.
The word commands' understanding of syntax is completely controlled by the syntax table. Any character can, for example, be declared to be a word delimiter. See section The Syntax Table.
The Emacs commands for manipulating sentences and paragraphs are mostly on Meta keys, so as to be like the word-handling commands.
backward-sentence).
forward-sentence).
kill-sentence).
backward-kill-sentence).
The commands M-a and M-e (backward-sentence and
forward-sentence) move to the beginning and end of the current
sentence, respectively. They were chosen to resemble C-a and
C-e, which move to the beginning and end of a line. Unlike them,
M-a and M-e if repeated or given numeric arguments move over
successive sentences.
Moving backward over a sentence places point just before the first character of the sentence; moving forward places point right after the punctuation that ends the sentence. Neither one moves over the whitespace at the sentence boundary.
Just as C-a and C-e have a kill command, C-k, to go
with them, so M-a and M-e have a corresponding kill command
M-k (kill-sentence) which kills from point to the end of
the sentence. With minus one as an argument it kills back to the
beginning of the sentence. Larger arguments serve as a repeat count.
There is also a command, C-x DEL
(backward-kill-sentence), for killing back to the beginning of a
sentence. This command is useful when you change your mind in the
middle of composing text.
The sentence commands assume that you follow the American typist's convention of putting two spaces at the end of a sentence; they consider a sentence to end wherever there is a `.', `?' or `!' followed by the end of a line or two spaces, with any number of `)', `]', `'', or `"' characters allowed in between. A sentence also begins or ends wherever a paragraph begins or ends.
The variable sentence-end controls recognition of the end of a
sentence. It is a regexp that matches the last few characters of a
sentence, together with the whitespace following the sentence. Its
normal value is
"[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"
This example is explained in the section on regexps. See section Syntax of Regular Expressions.
If you want to use just one space between sentences, you should
set sentence-end to this value:
"[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"
You should also set the variable sentence-end-double-space to
nil so that the fill commands expect and leave just one space at
the end of a sentence. Note that this makes it impossible to
distinguish between periods that end sentences and those that indicate
abbreviations.
The Emacs commands for manipulating paragraphs are also Meta keys.
backward-paragraph).
forward-paragraph).
mark-paragraph).
M-{ moves to the beginning of the current or previous paragraph, while M-} moves to the end of the current or next paragraph. Blank lines and text formatter command lines separate paragraphs and are not considered part of any paragraph. Also, an indented line starts a new paragraph.
In major modes for programs (as opposed to Text mode), paragraphs begin and end only at blank lines. This makes the paragraph commands continue to be useful even though there are no paragraphs per se.
When there is a fill prefix, then paragraphs are delimited by all lines which don't start with the fill prefix. See section Filling Text.
When you wish to operate on a paragraph, you can use the command
M-h (mark-paragraph) to set the region around it. Thus,
for example, M-h C-w kills the paragraph around or after point.
The M-h command puts point at the beginning and mark at the end of
the paragraph point was in. In Transient Mark mode, it activates the
mark. If point is between paragraphs (in a run of blank lines, or at a
boundary), the paragraph following point is surrounded by point and
mark. If there are blank lines preceding the first line of the
paragraph, one of these blank lines is included in the region.
The precise definition of a paragraph boundary is controlled by the
variables paragraph-separate and paragraph-start. The
value of paragraph-start is a regexp that should match any line
that either starts or separates paragraphs. The value of
paragraph-separate is another regexp that should match only lines
that separate paragraphs without being part of any paragraph. Lines
that start a new paragraph and are contained in it must match only
paragraph-start, not paragraph-separate. For example,
normally paragraph-start is "^[ \t\n\f]" and
paragraph-separate is "^[ \t\f]*$".
Normally it is desirable for page boundaries to separate paragraphs. The default values of these variables recognize the usual separator for pages.
Files are often thought of as divided into pages by the formfeed character (ASCII control-L, octal code 014). When you print hardcopy for a file, this character forces a page break; thus, each page of the file goes on a separate page on paper. Most Emacs commands treat the page-separator character just like any other character: you can insert it with C-q C-l, and delete it with DEL. Thus, you are free to paginate your file or not. However, since pages are often meaningful divisions of the file, Emacs provides commands to move over them and operate on them.
backward-page).
forward-page).
mark-page).
count-lines-page).
The C-x [ (backward-page) command moves point to immediately
after the previous page delimiter. If point is already right after a page
delimiter, it skips that one and stops at the previous one. A numeric
argument serves as a repeat count. The C-x ] (forward-page)
command moves forward past the next page delimiter.
The C-x C-p command (mark-page) puts point at the
beginning of the current page and the mark at the end. The page
delimiter at the end is included (the mark follows it). The page
delimiter at the front is excluded (point follows it). C-x C-p
C-w is a handy way to kill a page to move it elsewhere. If you move to
another page delimiter with C-x [ and C-x ], then yank the
killed page, all the pages will be properly delimited once again. The
reason C-x C-p includes only the following page delimiter in the
region is to ensure that.
A numeric argument to C-x C-p is used to specify which page to go to, relative to the current one. Zero means the current page. One means the next page, and -1 means the previous one.
The C-x l command (count-lines-page) is good for deciding
where to break a page in two. It prints in the echo area the total number
of lines in the current page, and then divides it up into those preceding
the current line and those following, as in
Page has 96 (72+25) lines
Notice that the sum is off by one; this is correct if point is not at the beginning of a line.
The variable page-delimiter controls where pages begin. Its
value is a regexp that matches the beginning of a line that separates
pages. The normal value of this variable is "^\f", which
matches a formfeed character at the beginning of a line.
Filling text means breaking it up into lines that fit a specified width. Emacs does filling in two ways. In Auto Fill mode, inserting text with self-inserting characters also automatically fills it. There are also explicit fill commands that you can use when editing text leaves it unfilled.
Auto Fill mode is a minor mode in which lines are broken automatically when they become too wide. Breaking happens only when you type a SPC or RET.
M-x auto-fill-mode turns Auto Fill mode on if it was off, or off if it was on. With a positive numeric argument it always turns Auto Fill mode on, and with a negative argument always turns it off. You can see when Auto Fill mode is in effect by the presence of the word `Fill' in the mode line, inside the parentheses. Auto Fill mode is a minor mode which is enabled or disabled for each buffer individually. See section Minor Modes.
In Auto Fill mode, lines are broken automatically at spaces when they get longer than the desired width. Line breaking and rearrangement takes place only when you type SPC or RET. If you wish to insert a space or newline without permitting line-breaking, type C-q SPC or C-q LFD (recall that a newline is really a linefeed). Also, C-o inserts a newline without line breaking.
Auto Fill mode works well with Lisp mode, because when it makes a new
line in Lisp mode it indents that line with TAB. If a line ending in
a comment gets too long, the text of the comment is split into two
comment lines. Optionally new comment delimiters are inserted at the end of
the first line and the beginning of the second so that each line is
a separate comment; the variable comment-multi-line controls the
choice (see section Manipulating Comments).
Auto Fill mode does not refill entire paragraphs; it can break lines but cannot merge lines. So editing in the middle of a paragraph can result in a paragraph that is not correctly filled. The easiest way to make the paragraph properly filled again is usually with the explicit fill commands.
Many users like Auto Fill mode and want to use it in all text files. The section on init files says how to arrange this permanently for yourself. See section The Init File, `~/.emacs'.
fill-paragraph).
set-fill-column).
fill-region).
To refill a paragraph, use the command M-q
(fill-paragraph). This operates on the paragraph that point is
inside, or the one after point if point is between paragraphs.
Refilling works by removing all the line-breaks, then inserting new ones
where necessary.
To refill many paragraphs, use M-x fill-region, which divides the region into paragraphs and fills each of them.
M-q and fill-region use the same criteria as M-h
for finding paragraph boundaries (see section Paragraphs). For more
control, you can use M-x fill-region-as-paragraph, which refills
everything between point and mark. This command deletes any blank lines
within the region, so separate blocks of text end up combined into one
block.
A numeric argument to M-q causes it to justify the text as
well as filling it. This means that extra spaces are inserted to make
the right margin line up exactly at the fill column. To remove the
extra spaces, use M-q with no argument. (Likewise for
fill-region.)
When adaptive-fill-mode is non-nil (which is normally
the case), if you use fill-region-as-paragraph on an indented
paragraph and you don't have a fill prefix, it uses the indentation of
the second line of the paragraph as the fill prefix. The effect of
adaptive filling is not noticeable in Text mode, because an indented
line counts as a paragraph starter and thus each line of an indented
paragraph is considered a paragraph of its own. But you do notice the
effect in Indented Text mode and some other major modes.
The command M-s (center-line) centers the current line
within the current fill column. With an argument n, it centers
n lines individually and moves past them.
The maximum line width for filling is in the variable
fill-column. Altering the value of fill-column makes it
local to the current buffer; until that time, the default value is in
effect. The default is initially 70. See section Local Variables. The easiest way
to set fill-column is to use the command C-x f
(set-fill-column). With no argument, it sets fill-column
to the current horizontal position of point. With a numeric argument,
it uses that as the new fill column.
Emacs commands normally consider a period followed by two spaces or by a newline as the end of a sentence; a period followed by just one space indicates an abbreviation and not the end of a sentence. To preserve the distinction between these two ways of using a period, the fill commands do not break a line after a period followed by just one space.
If the variable sentence-end-double-space is nil, the
fill commands expect and leave just one space at the end of a sentence.
Ordinarily this variable is t, so the fill commands insist on
two spaces for the end of a sentence, as explained above. See section Sentences.
To fill a paragraph in which each line starts with a special marker (which might be a few spaces, giving an indented paragraph), use the fill prefix feature. The fill prefix is a string which Emacs expects every line to start with, and which is not included in filling.
set-fill-prefix).
fill-paragraph).
To specify a fill prefix, move to a line that starts with the desired
prefix, put point at the end of the prefix, and give the command
C-x . (set-fill-prefix). That's a period after the
C-x. To turn off the fill prefix, specify an empty prefix: type
C-x . with point at the beginning of a line.
When a fill prefix is in effect, the fill commands remove the fill prefix from each line before filling and insert it on each line after filling. Auto Fill mode also inserts the fill prefix automatically when it makes a new line. The C-o command inserts the fill prefix on new lines it creates, when you use it at the beginning of a line (see section Blank Lines). Conversely, the command M-^ deletes the prefix (if it occurs) after the newline that it deletes (see section Indentation).
For example, if fill-column is 40 and you set the fill prefix
to `;; ', then M-q in the following text
;; This is an ;; example of a paragraph ;; inside a Lisp-style comment.
produces this:
;; This is an example of a paragraph ;; inside a Lisp-style comment.
Lines that do not start with the fill prefix are considered to start paragraphs, both in M-q and the paragraph commands; this is gives good results for paragraphs with hanging indentation (every line indented except the first one). Lines which are blank or indented once the prefix is removed also separate or start paragraphs; this is what you want if you are writing multi-paragraph comments with a comment delimiter on each line.
You can use M-x fill-individual-paragraphs to set the fill prefix for each paragraph automatically. This command divides the region into paragraphs, treating every change in the amount of indentation as the start of a new paragraph, and fills each of these paragraphs. Thus, all the lines in one "paragraph" have the same amount of indentation. That indentation serves as the fill prefix for that paragraph.
M-x fill-nonuniform-paragraphs is a similar command that divides
the region into paragraphs in a different way. It considers only
paragraph-separating lines (as defined by paragraph-separate) as
starting a new paragraph. Since this means that the lines of one
paragraph may have different amounts of indentation, the fill prefix
used is the smallest amount of indentation of any of the lines of the
paragraph. This gives good results with styles that indent a paragraph's
first line more or less that the rest of the paragraph.
The fill prefix is stored in the variable fill-prefix. Its value
is a string, or nil when there is no fill prefix. This is a
per-buffer variable; altering the variable affects only the current buffer,
but there is a default value which you can change as well. See section Local Variables.
Emacs has commands for converting either a single word or any arbitrary range of text to upper case or to lower case.
downcase-word).
upcase-word).
capitalize-word).
downcase-region).
upcase-region).
The word conversion commands are the most useful. M-l
(downcase-word) converts the word after point to lower case, moving
past it. Thus, repeating M-l converts successive words.
M-u (upcase-word) converts to all capitals instead, while
M-c (capitalize-word) puts the first letter of the word
into upper case and the rest into lower case. All these commands convert
several words at once if given an argument. They are especially convenient
for converting a large amount of text from all upper case to mixed case,
because you can move through the text using M-l, M-u or
M-c on each word as appropriate, occasionally using M-f instead
to skip a word.
When given a negative argument, the word case conversion commands apply to the appropriate number of words before point, but do not move point. This is convenient when you have just typed a word in the wrong case: you can give the case conversion command and continue typing.
If a word case conversion command is given in the middle of a word, it
applies only to the part of the word which follows point. This is just
like what M-d (kill-word) does. With a negative argument,
case conversion applies only to the part of the word before point.
The other case conversion commands are C-x C-u
(upcase-region) and C-x C-l (downcase-region), which
convert everything between point and mark to the specified case. Point and
mark do not move.
The region case conversion commands upcase-region and
downcase-region are normally disabled. This means that they ask
for confirmation if you try to use them. When you confirm, you may
enable the command, which means it will not ask for confirmation again.
See section Disabling Commands.
When you edit files of text in a human language, it's more convenient
to use Text mode rather than Fundamental mode. Invoke M-x
text-mode to enter Text mode. In Text mode, TAB runs the
function tab-to-tab-stop, which allows you to use arbitrary tab
stops set with M-x edit-tab-stops (see section Tab Stops). Features
concerned with comments in programs are turned off in Text mode except
when explicitly invoked. The syntax table is changed so that periods
are not considered part of a word, while apostrophes, backspaces and
underlines are part of words.
A similar variant mode is Indented Text mode, intended for editing
text in which most lines are indented. This mode defines TAB to
run indent-relative (see section Indentation), and makes Auto Fill
indent the lines it creates. The result is that normally a line made by
Auto Filling, or by LFD, is indented just like the previous line.
In Indented Text mode, only blank lines separate paragraphs--indented
lines continue the current paragraph. Use M-x indented-text-mode
to select this mode.
Text mode, and all the modes based on it, define M-TAB as
the command ispell-complete-word, which performs completion of
the partial word in the buffer before point, using the spelling
dictionary as the space of possible words. See section Checking and Correcting Spelling.
Entering Text mode or Indented Text mode runs the hook
text-mode-hook. Other major modes related to Text mode also run
this hook, followed by hooks of their own; this includes Nroff mode,
TeX mode, Outline mode and Mail mode. Hook functions on
text-mode-hook can look at the value of major-mode to see
which of these modes is actually being entered. See section Hooks.
Outline mode is a major mode much like Text mode but intended for editing outlines. It allows you to make parts of the text temporarily invisible so that you can see the outline structure. Type M-x outline-mode to switch to Outline mode as the major mode of the current buffer. Type M-x outline-minor-mode to enable Outline mode as a minor mode in the current buffer. Outline minor mode provides the same commands as the major mode, Outline mode, but you can use it in conjunction with other major modes.
The major mode, Outline mode, provides special key bindings on the
C-c prefix. Outline minor mode provides similar bindings with
C-c C-o as the prefix; this is to reduce the conflicts with the
major mode's special commands. (The variable
outline-minor-mode-prefix controls the prefix used.)
When Outline mode makes a line invisible, the line does not appear on the screen. The screen appears exactly as if the invisible line were deleted, except that an ellipsis (three periods in a row) appears at the end of the previous visible line (only one ellipsis no matter how many invisible lines follow).
All editing commands treat the text of the invisible line as part of the previous visible line. For example, C-n moves onto the next visible line. Killing an entire visible line, including its terminating newline, really kills all the following invisible lines along with it; yanking it all back yanks the invisible lines and they remain invisible.
Entering Outline mode runs the hook text-mode-hook followed by
the hook outline-mode-hook (see section Hooks).
Outline mode assumes that the lines in the buffer are of two types: heading lines and body lines. A heading line represents a topic in the outline. Heading lines start with one or more stars; the number of stars determines the depth of the heading in the outline structure. Thus, a heading line with one star is a major topic; all the heading lines with two stars between it and the next one-star heading are its subtopics; and so on. Any line that is not a heading line is a body line. Body lines belong with the preceding heading line. Here is an example:
* Food This is the body, which says something about the topic of food. ** Delicious Food This is the body of the second-level header. ** Distasteful Food This could have a body too, with several lines. *** Dormitory Food * Shelter Another first-level topic with its header line.
A heading line together with all following body lines is called collectively an entry. A heading line together with all following deeper heading lines and their body lines is called a subtree.
You can customize the criterion for distinguishing heading lines
by setting the variable outline-regexp. Any line whose
beginning has a match for this regexp is considered a heading line.
Matches that start within a line (not at the left margin) do not count.
The length of the matching text determines the level of the heading;
longer matches make a more deeply nested level. Thus, for example,
if a text formatter has commands `@chapter', `@section'
and `@subsection' to divide the document into chapters and
sections, you could make those lines count as heading lines by
setting outline-regexp to `"@chap\\|@\\(sub\\)*section"'.
Note the trick: the two words `chapter' and `section' are equally
long, but by defining the regexp to match only `chap' we ensure
that the length of the text matched on a chapter heading is shorter,
so that Outline mode will know that sections are contained in chapters.
This works as long as no other command starts with `@chap'.
It is possible to change the rule for calculating the level of a
heading line by setting the variable outline-level. The value of
outline-level should be a function that takes no arguments and
returns the level of the current heading. Some major modes such as C,
Nroff, and Emacs Lisp mode set this variable in order to work with
Outline minor mode.
Outline mode makes a line invisible by changing the newline before it into an ASCII control-M (code 015). Most editing commands that work on lines treat an invisible line as part of the previous line because, strictly speaking, it is part of that line, since there is no longer a newline in between. When you save the file in Outline mode, control-M characters are saved as newlines, so the invisible lines become ordinary lines in the file. But saving does not change the visibility status of a line inside Emacs.
There are some special motion commands in Outline mode that move backward and forward to heading lines.
outline-next-visible-heading).
outline-previous-visible-heading).
outline-forward-same-level).
outline-backward-same-level).
outline-up-heading).
C-c C-n (next-visible-heading) moves down to the next
heading line. C-c C-p (previous-visible-heading) moves
similarly backward. Both accept numeric arguments as repeat counts. The
names emphasize that invisible headings are skipped, but this is not really
a special feature. All editing commands that look for lines ignore the
invisible lines automatically.
More powerful motion commands understand the level structure of headings.
C-c C-f (outline-forward-same-level) and
C-c C-b (outline-backward-same-level) move from one
heading line to another visible heading at the same depth in
the outline. C-c C-u (outline-up-heading) moves
backward to another heading that is less deeply nested.
The other special commands of outline mode are used to make lines visible
or invisible. Their names all start with hide or show.
Most of them fall into pairs of opposites. They are not undoable; instead,
you can undo right past them. Making lines visible or invisible is simply
not recorded by the undo mechanism.
hide-body).
show-all).
hide-subtree).
show-subtree).
hide-leaves).
show-branches).
show-children).
hide-entry).
show-entry).
hide-sublevels).
hide-other).
Two commands that are exact opposites are C-c C-c
(hide-entry) and C-c C-e (show-entry). They are
used with point on a heading line, and apply only to the body lines of
that heading. Subheadings and their bodies are not affected.
Two more powerful opposites are C-c C-d (hide-subtree) and
C-c C-s (show-subtree). Both expect to be used when point is
on a heading line, and both apply to all the lines of that heading's
subtree: its body, all its subheadings, both direct and indirect, and
all of their bodies. In other words, the subtree contains everything
following this heading line, up to and not including the next heading of
the same or higher rank.
Intermediate between a visible subtree and an invisible one is having
all the subheadings visible but none of the body. There are two
commands for doing this, depending on whether you want to hide the
bodies or make the subheadings visible. They are C-c C-l
(hide-leaves) and C-c C-k (show-branches).
A little weaker than show-branches is C-c C-i
(show-children). It makes just the direct subheadings
visible--those one level down. Deeper subheadings remain invisible, if
they were invisible.
Two commands have a blanket effect on the whole file. C-c C-t
(hide-body) makes all body lines invisible, so that you see just
the outline structure. C-c C-a (show-all) makes all lines
visible. These commands can be thought of as a pair of opposites even
though C-c C-a applies to more than just body lines.
The command C-c C-q (hide-sublevels) hides all but the
top level headings. With a numeric argument n, it hides everything
except the top n levels of heading lines.
The command C-c C-o (hide-other) hides everything except
the heading or body text that point is in, plus its parents (the headers
leading up from there to top level in the outline).
You can turn off the use of ellipses at the ends of visible lines by
setting selective-display-ellipses to nil. Then there is
no visible indication of the presence of invisible lines.
TeX is a powerful text formatter written by Donald Knuth; it is also free, like GNU Emacs. LaTeX is a simplified input format for TeX, implemented by TeX macros; it comes with TeX. SliTeX is a special form of LaTeX.
Emacs has a special TeX mode for editing TeX input files. It provides facilities for checking the balance of delimiters and for invoking TeX on all or part of the file.
TeX mode has three variants, Plain TeX mode, LaTeX mode, and
SliTeX mode (these three distinct major modes differ only slightly).
They are designed for editing the three different formats. The command
M-x tex-mode looks at the contents of the buffer to determine
whether the contents appear to be either LaTeX input or SliTeX
input; if so, it selects the appropriate mode. If the file contents do
not appear to be LaTeX or SliTeX, it selects Plain TeX mode.
If the contents are insufficient to determine this, the variable
tex-default-mode controls which mode is used.
When M-x tex-mode does not guess right, you can use the commands M-x plain-tex-mode, M-x latex-mode, and M-x slitex-mode to select explicitly the particular variants of TeX mode.
Here are the special commands provided in TeX mode for editing the text of the file.
tex-insert-quote).
tex-terminate-paragraph).
tex-insert-braces).
up-list).
In TeX, the character `"' is not normally used; we use
`"' to start a quotation and `"' to end one. To make
editing easier under this formatting convention, TeX mode overrides
the normal meaning of the key " with a command that inserts a pair
of single-quotes or backquotes (tex-insert-quote). To be
precise, this command inserts `"' after whitespace or an open
brace, `"' after a backslash, and `"' after any other
character.
If you need the character `"' itself in unusual contexts, use C-q to insert it. Also, " with a numeric argument always inserts that number of `"' characters.
In TeX mode, `$' has a special syntax code which attempts to understand the way TeX math mode delimiters match. When you insert a `$' that is meant to exit math mode, the position of the matching `$' that entered math mode is displayed for a second. This is the same feature that displays the open brace that matches a close brace that is inserted. However, there is no way to tell whether a `$' enters math mode or leaves it; so when you insert a `$' that enters math mode, the previous `$' position is shown as if it were a match, even though they are actually unrelated.
TeX uses braces as delimiters that must match. Some users prefer
to keep braces balanced at all times, rather than inserting them
singly. Use C-c { (tex-insert-braces) to insert a pair of
braces. It leaves point between the two braces so you can insert the
text that belongs inside. Afterward, use the command C-c }
(up-list) to move forward past the close brace.
There are two commands for checking the matching of braces. LFD
(tex-terminate-paragraph) checks the paragraph before point, and
inserts two newlines to start a new paragraph. It prints a message in
the echo area if any mismatch is found. M-x validate-tex-region
checks a region, paragraph by paragraph. When it finds a paragraph that
contains a mismatch, it displays point at the beginning of the paragraph
for a few seconds and sets the mark at that spot. Scanning continues
until the whole buffer has been checked or until you type another key.
Afterward, you can use the mark ring to find the last several paragraphs
that had mismatches (see section The Mark Ring).
Note that Emacs commands count square brackets and parentheses in TeX mode, not just braces. This is not strictly correct for the purpose of checking TeX syntax. However, parentheses and square brackets are likely to be used in text as matching delimiters and it is useful for the various motion commands and automatic match display to work with them.
LaTeX mode, and its variant, SliTeX mode, provide a few extra features not applicable to plain TeX.
tex-latex-block).
tex-close-latex-block).
In LaTeX input, `\begin' and `\end' commands are used to
group blocks of text. To insert a `\begin' and a matching
`\end' (on a new line following the `\begin'), use C-c
C-o (tex-latex-block). A blank line is inserted between the
two, and point is left there. You can use completion when you enter the
block type; to specify additional block type names beyond the standard
list, set the variable latex-block-names. For example, here's
how to add `theorem', `corollary', and `proof':
(setq latex-block-names '("theorem" "corollary" "proof"))
In LaTeX input, `\begin' and `\end' commands must
balance. You can use C-c C-e (tex-close-latex-block) to
insert automatically a matching `\end' to match the last unmatched
`\begin'. It indents the `\end' to match the corresponding
`\begin'. It inserts a newline after `\end' if point is at
the beginning of a line.
You can invoke TeX as an inferior of Emacs on either the entire contents of the buffer or just a region at a time. Running TeX in this way on just one chapter is a good way to see what your changes look like without taking the time to format the entire file.
tex-region).
tex-buffer).
tex-bibtex-file).
tex-file).
tex-recenter-output-buffer).
tex-kill-job).
tex-print).
tex-view).
tex-show-print-queue).
You can pass the current buffer through an inferior TeX by means of
C-c C-b (tex-buffer). The formatted output appears in a
temporary file; to print it, type C-c C-p (tex-print).
Afterward, you can use C-c C-q (tex-show-print-queue) to
view the progress of your output towards being printed. If your terminal
has the ability to display TeX output files, you can preview the
output on the terminal with C-c C-v (tex-view).
You can specify the directory to use for running TeX by setting the
variable tex-directory. "." is the default value. If
your environment variable TEXINPUTS contains relative directory
names, or if your files contains `\input' commands with relative
file names, then tex-directory must be "." or you
will get the wrong results. Otherwise, it is safe to specify some other
directory, such as "/tmp".
If you want to specify which shell commands are used in the inferior TeX,
you can do so by setting the values of the variables tex-run-command,
latex-run-command, slitex-run-command,
tex-dvi-print-command, tex-dvi-view-command, and
tex-show-queue-command. You must set the value of
tex-dvi-view-command for your particular terminal; this variable
has no default value. The other variables have default values that may
(or may not) be appropriate for your system.
Normally, the file name given to these commands comes at the end of the command string; for example, `latex filename'. In some cases, however, the file name needs to be embedded in the command; an example is when you need to provide the file name as an argument to one command whose output is piped to another. You can specify where to put the file name with `*' in the command string. For example,
(setq tex-dvi-print-command "dvips -f * | lpr")
The terminal output from TeX, including any error messages, appears in a buffer called `*tex-shell*'. If TeX gets an error, you can switch to this buffer and feed it input (this works as in Shell mode; see section Interactive Inferior Shell). Without switching to this buffer you can scroll it so that its last line is visible by typing C-c C-l.
Type C-c C-k (tex-kill-job) to kill the TeX process if
you see that its output is no longer useful. Using C-c C-b or
C-c C-r also kills any TeX process still running.
You can also pass an arbitrary region through an inferior TeX by typing
C-c C-r (tex-region). This is tricky, however, because most files
of TeX input contain commands at the beginning to set parameters and
define macros, without which no later part of the file will format
correctly. To solve this problem, C-c C-r allows you to designate a
part of the file as containing essential commands; it is included before
the specified region as part of the input to TeX. The designated part
of the file is called the header.
To indicate the bounds of the header in Plain TeX mode, you insert two special strings in the file. Insert `%**start of header' before the header, and `%**end of header' after it. Each string must appear entirely on one line, but there may be other text on the line before or after. The lines containing the two strings are included in the header. If `%**start of header' does not appear within the first 100 lines of the buffer, C-c C-r assumes that there is no header.
In LaTeX mode, the header begins with `\documentstyle' and ends with `\begin{document}'. These are commands that LaTeX requires you to use in any case, so nothing special needs to be done to identify the header.
The commands (tex-buffer) and (tex-region) do all of their
work in a temporary directory, and do not have available any of the auxiliary
files needed by TeX for cross-references; these commands are generally
not suitable for running the final copy in which all of the cross-references
need to be correct. When you want the auxiliary files, use C-c C-f
(tex-file) which runs TeX on the current buffer's file, in that
file's directory. Before TeX runs, you will be asked about saving
any modified buffers. Generally, you need to use (tex-file)
twice to get cross-references correct.
For LaTeX files, you can use BibTeX to process the auxiliary
file for the current buffer's file. BibTeX looks up bibliographic
citations in a data base and prepares the cited references for the
bibliography section. The command C-c TAB
(tex-bibtex-file) runs the shell command
(tex-bibtex-command) to produce a `.bbl' file for the
current buffer's file. Generally, you need to do C-c C-f
(tex-file) once to generate the `.aux' file, then do
C-c TAB (tex-bibtex-file), and then repeat C-c C-f
(tex-file) twice more to get the cross-references correct.
Entering any kind of TeX mode runs the hooks text-mode-hook
and tex-mode-hook. Then it runs either
plain-tex-mode-hook or latex-mode-hook, whichever is
appropriate. For SliTeX files, it calls slitex-mode-hook.
Starting the TeX shell runs the hook tex-shell-hook.
See section Hooks.
TeX for Unix systems can be obtained from the University of Washington for a distribution fee.
To order a full distribution, specify whether you prefer 1/4 inch QIC-24 or 4mm DAT tape (9-track reel-to-reel is no longer available) and send $210.00 for a (tar or cpio) cartridge, payable to the University of Washington to:
Pierre MacKay Department of Classics Denny Hall, Mail Stop DH-10 University of Washington Seattle, Washington 98195
Purchase orders are acceptable, but there is an extra charge of $10.00, to pay for processing charges.
For overseas orders please add $20.00 to the base cost for shipment via air parcel post, or $30.00 for shipment via courier.
The normal distribution is a tar tape, blocked 20, 1600 bpi, on an industry standard 2400 foot half-inch reel. The physical format for the 1/4 inch streamer cartridges is QIC-24. System V tapes can be written in cpio format, blocked 5120 bytes, with ASCII headers.
Nroff mode is a mode like Text mode but modified to handle nroff commands present in the text. Invoke M-x nroff-mode to enter this mode. It differs from Text mode in only a few ways. All nroff command lines are considered paragraph separators, so that filling will never garble the nroff commands. Pages are separated by `.bp' commands. Comments start with backslash-doublequote. Also, three special commands are provided that are not in Text mode:
forward-text-line). An argument is a repeat count.
backward-text-line).
count-text-lines).
The other feature of Nroff mode is that you can turn on Electric Nroff mode. This is a minor mode that you can turn on or off with M-x electric-nroff-mode (see section Minor Modes). When the mode is on, each time you use RET to end a line that contains an nroff command that opens a kind of grouping, the matching nroff command to close that grouping is automatically inserted on the following line. For example, if you are at the beginning of a line and type . ( b RET, this inserts the matching command `.)b' on a new line following point.
If you use Outline minor mode with Nroff mode (see section Outline Mode), heading lines are lines of the form `.H' followed by a number (the header level).
Entering Nroff mode runs the hook text-mode-hook, followed by
the hook nroff-mode-hook (see section Hooks).
Emacs has many commands designed to understand the syntax of programming languages such as Lisp and C. These commands can
The commands for words, sentences and paragraphs are very useful in editing code even though their canonical application is for editing human language text. Most symbols contain words (see section Words); sentences can be found in strings and comments (see section Sentences). Paragraphs per se don't exist in code, but the paragraph commands are useful anyway, because programming language major modes define paragraphs to begin and end at blank lines (see section Paragraphs). Judicious use of blank lines to make the program clearer will also provide useful chunks of text for the paragraph commands to work on.
The selective display feature is useful for looking at the overall structure of a function (see section Selective Display). This feature causes only the lines that are indented less than a specified amount to appear on the screen.
Emacs also has major modes for the programming languages Lisp, Scheme (a variant of Lisp), Awk, C, C++, Fortran, Icon, Pascal, Perl and Tcl. There is also a major mode for makefiles, called Makefile mode.
Ideally, a major mode should be implemented for each programming language that you might want to edit with Emacs; but often the mode for one language can serve for other syntactically similar languages. The language modes that exist are those that someone decided to take the trouble to write.
There are several forms of Lisp mode, which differ in the way they interface to Lisp execution. See section Executing Lisp Expressions.
Each of the programming language modes defines the TAB key to run
an indentation function that knows the indentation conventions of that
language and updates the current line's indentation accordingly. For
example, in C mode TAB is bound to c-indent-line. LFD
is normally defined to do RET followed by TAB; thus, it too
indents in a mode-specific fashion.
In most programming languages, indentation is likely to vary from line to
line. So the major modes for those languages rebind DEL to treat a
tab as if it were the equivalent number of spaces (using the command
backward-delete-char-untabify). This makes it possible to rub out
indentation one column at a time without worrying whether it is made up of
spaces or tabs. Use C-b C-d to delete a tab character before point,
in these modes.
Programming language modes define paragraphs to be separated only by blank lines, so that the paragraph commands remain useful. Auto Fill mode, if enabled in a programming language major mode, indents the new lines which it creates.
Turning on a major mode runs a normal hook called the mode hook,
which is the value of a Lisp variable. Each major mode has a mode hook,
and the hook's name is always made from the mode command's name by
adding `-hook'. For example, turning on C mode runs the hook
c-mode-hook, while turning on Lisp mode runs the hook
lisp-mode-hook. See section Hooks.
By convention, Emacs keys for dealing with balanced expressions are usually Control-Meta characters. They tend to be analogous in function to their Control and Meta equivalents. These commands are usually thought of as pertaining to expressions in programming languages, but can be useful with any language in which some sort of parentheses exist (including human languages).
These commands fall into two classes. Some deal only with lists (parenthetical groupings). They see nothing except parentheses, brackets, braces (whichever ones must balance in the language you are working with), and escape characters that might be used to quote those.
The other commands deal with expressions or sexps. The word `sexp' is derived from s-expression, the ancient term for an expression in Lisp. But in Emacs, the notion of `sexp' is not limited to Lisp. It refers to an expression in whatever language your program is written in. Each programming language has its own major mode, which customizes the syntax tables so that expressions in that language count as sexps.
Sexps typically include symbols, numbers, and string constants, as well as anything contained in parentheses, brackets or braces.
In languages that use prefix and infix operators, such as C, it is not possible for all expressions to be sexps. For example, C mode does not recognize `foo + bar' as a sexp, even though it is a C expression; it recognizes `foo' as one sexp and `bar' as another, with the `+' as punctuation between them. This is a fundamental ambiguity: both `foo + bar' and `foo' are legitimate choices for the sexp to move over if point is at the `f'. Note that `(foo + bar)' is a single sexp in C mode.
Some languages have obscure forms of expression syntax that nobody has bothered to make Emacs understand properly.
forward-sexp).
backward-sexp).
kill-sexp).
backward-kill-sexp).
backward-up-list).
down-list).
forward-list).
backward-list).
transpose-sexps).
mark-sexp).
To move forward over a sexp, use C-M-f (forward-sexp). If
the first significant character after point is an opening delimiter
(`(' in Lisp; `(', `[' or `{' in C), C-M-f
moves past the matching closing delimiter. If the character begins a
symbol, string, or number, C-M-f moves over that.
The command C-M-b (backward-sexp) moves backward over a
sexp. The detailed rules are like those above for C-M-f, but with
directions reversed. If there are any prefix characters (single-quote,
backquote and comma, in Lisp) preceding the sexp, C-M-b moves back
over them as well. The sexp commands move across comments as if they
were whitespace in most modes.
C-M-f or C-M-b with an argument repeats that operation the specified number of times; with a negative argument, it moves in the opposite direction.
Killing a sexp at a time can be done with C-M-k
(kill-sexp) or C-M-DEL (backward-kill-sexp).
C-M-k kills the characters that C-M-f would move over, and
C-M-DEL kills the characters that C-M-b would move
over.
The list commands move over lists like the sexp commands but skip
blithely over any number of other kinds of sexps (symbols, strings, etc).
They are C-M-n (forward-list) and C-M-p
(backward-list). The main reason they are useful is that they
usually ignore comments (since the comments usually do not contain any
lists).
C-M-n and C-M-p stay at the same level in parentheses, when
that's possible. To move up one (or n) levels, use C-M-u
(backward-up-list).
C-M-u moves backward up past one unmatched opening delimiter. A
positive argument serves as a repeat count; a negative argument reverses
direction of motion and also requests repetition, so it moves forward and
up one or more levels.
To move down in list structure, use C-M-d (down-list). In Lisp mode,
where `(' is the only opening delimiter, this is nearly the same as
searching for a `('. An argument specifies the number of levels
of parentheses to go down.
A somewhat random-sounding command which is nevertheless handy is
C-M-t (transpose-sexps), which drags the previous sexp
across the next one. An argument serves as a repeat count, and a
negative argument drags backwards (thus canceling out the effect of
C-M-t with a positive argument). An argument of zero, rather than
doing nothing, transposes the sexps ending after point and the mark.
To set the region around the next sexp in the buffer, use C-M-@
(mark-sexp), which sets mark at the same place that C-M-f
would move to. C-M-@ takes arguments like C-M-f. In
particular, a negative argument is useful for putting the mark at the
beginning of the previous sexp.
The list and sexp commands' understanding of syntax is completely controlled by the syntax table. Any character can, for example, be declared to be an opening delimiter and act like an open parenthesis. See section The Syntax Table.
In Emacs, a parenthetical grouping at the top level in the buffer is
called a defun. The name derives from the fact that most top-level
lists in a Lisp file are instances of the special form defun, but
any top-level parenthetical grouping counts as a defun in Emacs parlance
regardless of what its contents are, and regardless of the programming
language in use. For example, in C, the body of a function definition is a
defun.
beginning-of-defun).
end-of-defun).
mark-defun).
The commands to move to the beginning and end of the current defun are
C-M-a (beginning-of-defun) and C-M-e (end-of-defun).
If you wish to operate on the current defun, use C-M-h
(mark-defun) which puts point at the beginning and mark at the end
of the current or next defun. For example, this is the easiest way to get
ready to move the defun to a different place in the text. In C mode,
C-M-h runs the function mark-c-function, which is almost the
same as mark-defun; the difference is that it backs up over the
argument declarations, function name and returned data type so that the
entire C function is inside the region. See section Commands to Mark Textual Objects.
Emacs assumes that any open-parenthesis found in the leftmost column is the start of a defun. Therefore, never put an open-parenthesis at the left margin in a Lisp file unless it is the start of a top level list. Never put an open-brace or other opening delimiter at the beginning of a line of C code unless it starts the body of a function. The most likely problem case is when you want an opening delimiter at the start of a line inside a string. To avoid trouble, put an escape character (`\', in C and Emacs Lisp, `/' in some other Lisp dialects) before the opening delimiter. It will not affect the contents of the string.
In the remotest past, the original Emacs found defuns by moving upward a level of parentheses until there were no more levels to go up. This always required scanning all the way back to the beginning of the buffer, even for a small function. To speed up the operation, Emacs was changed to assume that any `(' (or other character assigned the syntactic class of opening-delimiter) at the left margin is the start of a defun. This heuristic is nearly always right and avoids the costly scan; however, it mandates the convention described above.
The best way to keep a program properly indented is to use Emacs to re-indent it as you change it. Emacs has commands to indent properly either a single line, a specified number of lines, or all of the lines inside a single parenthetical grouping.
Emacs also provides a Lisp pretty-printer in the library pp.
This program prints a Lisp object with indentation chosen to look nice.
newline-and-indent).
The basic indentation command is TAB, which gives the current line
the correct indentation as determined from the previous lines. The
function that TAB runs depends on the major mode; it is lisp-indent-line
in Lisp mode, c-indent-line in C mode, etc. These functions
understand different syntaxes for different languages, but they all do
about the same thing. TAB in any programming language major mode
inserts or deletes whitespace at the beginning of the current line,
independent of where point is in the line. If point is inside the
whitespace at the beginning of the line, TAB leaves it at the end of
that whitespace; otherwise, TAB leaves point fixed with respect to
the characters around it.
Use C-q TAB to insert a tab at point.
When entering lines of new code, use LFD (newline-and-indent),
which is equivalent to a RET followed by a TAB. LFD creates
a blank line, and then gives it the appropriate indentation.
TAB indents the second and following lines of the body of a parenthetical grouping each under the preceding one; therefore, if you alter one line's indentation to be nonstandard, the lines below will tend to follow it. This behavior is convenient in cases where you have overridden the standard result of TAB because you find it unaesthetic for a particular line.
Remember that an open-parenthesis, open-brace or other opening delimiter at the left margin is assumed by Emacs (including the indentation routines) to be the start of a function. Therefore, you must never have an opening delimiter in column zero that is not the beginning of a function, not even inside a string. This restriction is vital for making the indentation commands fast; you must simply accept it. See section Defuns, for more information on this.
When you wish to re-indent several lines of code which have been altered or moved to a different level in the list structure, you have several commands available.
indent-sexp).
indent-region).
You can re-indent the contents of a single list by positioning point
before the beginning of it and typing C-M-q (indent-sexp in
Lisp mode, indent-c-exp in C mode; also bound to other suitable
commands in other modes). The indentation of the line the sexp starts on
is not changed; therefore, only the relative indentation within the list,
and not its position, is changed. To correct the position as well, type a
TAB before the C-M-q.
If the relative indentation within a list is correct but the indentation of its first line is not, go to that line and type C-u TAB. TAB with a numeric argument reindents the current line as usual, then reindents by the same amount all the lines in the grouping starting on the current line. In other words, it reindents the whole grouping rigidly as a unit. It is clever, though, and does not alter lines that start inside strings, or C preprocessor lines when in C mode.
Another way to specify the range to be re-indented is with the region.
The command C-M-\ (indent-region) applies TAB to
every line whose first character is between point and mark.
The indentation pattern for a Lisp expression can depend on the function called by the expression. For each Lisp function, you can choose among several predefined patterns of indentation, or define an arbitrary one with a Lisp program.
The standard pattern of indentation is as follows: the second line of the expression is indented under the first argument, if that is on the same line as the beginning of the expression; otherwise, the second line is indented underneath the function name. Each following line is indented under the previous line whose nesting depth is the same.
If the variable lisp-indent-offset is non-nil, it overrides
the usual indentation pattern for the second line of an expression, so that
such lines are always indented lisp-indent-offset more columns than
the containing list.
The standard pattern is overridden for certain functions. Functions
whose names start with def always indent the second line by
lisp-body-indent extra columns beyond the open-parenthesis
starting the expression.
The standard pattern can be overridden in various ways for individual
functions, according to the lisp-indent-hook property of the
function name. There are four possibilities for this property:
nil
defun
def is used for
this function also.
lisp-body-indent
more columns than the open-parenthesis starting the containing
expression. If the argument is distinguished and is either the first
or second argument, it is indented twice that many extra columns.
If the argument is distinguished and not the first or second argument,
the standard pattern is followed for that line.
parse-partial-sexp (a Lisp primitive for
indentation and nesting computation) when it parses up to the
beginning of this line.
Two variables control which commands perform C indentation and when.
If c-auto-newline is non-nil, newlines are inserted both
before and after braces that you insert, and after colons and semicolons.
Correct C indentation is done on all the lines that are made this way.
If c-tab-always-indent is nil, the TAB command in
C mode does indentation only if point is at the left margin or within
the line's indentation. If there is non-whitespace to the left of
point, then TAB just inserts a tab character in the buffer.
Normally, this variable is t, and TAB always reindents the
current line. The default behavior means that to insert a real tab
character you must quote it by typing C-q TAB.
C does not have anything analogous to particular function names for which special forms of indentation are desirable. However, it has a different need for customization facilities: many different styles of C indentation are in common use.
There are six variables you can set to control the style that Emacs C mode uses.
c-indent-level
c-continued-statement-offset
c-brace-offset
c-brace-imaginary-offset
c-argdecl-indent
c-label-offset
The variable c-indent-level controls the indentation for C
statements with respect to the surrounding block. In the example
{
foo ();
the difference in indentation between the lines is c-indent-level.
Its standard value is 2.
If the open-brace beginning the compound statement is not at the beginning
of its line, the c-indent-level is added to the indentation of the
line, not the column of the open-brace. For example,
if (losing) {
do_this ();
One popular indentation style is that which results from setting
c-indent-level to 8 and putting open-braces at the end of a line in
this way. I prefer to put the open-brace on a separate line.
In fact, the value of the variable c-brace-imaginary-offset is
also added to the indentation of such a statement. Normally this variable
is zero. Think of this variable as the imaginary position of the open
brace, relative to the first nonblank character on the line. By setting
this variable to 4 and c-indent-level to 0, you can get this style:
if (x == y) {
do_it ();
}
When c-indent-level is zero, the statements inside most braces
will line up right under the open brace. But there is an exception made
for braces in column zero, such as surrounding a function's body. The
statements just inside it do not go at column zero. Instead,
c-brace-offset and c-continued-statement-offset (see below)
are added to produce a typical offset between brace levels, and the
statements are indented that far.
c-continued-statement-offset controls the extra indentation for a
line that starts within a statement (but not within parentheses or
brackets). These lines are usually statements that are within other
statements, such as the then-clauses of if statements and the bodies
of while statements. This parameter is the difference in
indentation between the two lines in
if (x == y) do_it ();
Its standard value is 2. Some popular indentation styles correspond to a
value of zero for c-continued-statement-offset.
c-brace-offset is the extra indentation given to a line that
starts with an open-brace. Its standard value is zero;
compare
if (x == y)
{
with
if (x == y) do_it ();
if c-brace-offset were set to 4, the first example would become
if (x == y)
{
c-argdecl-indent controls the indentation of declarations of the
arguments of a C function. It is absolute: argument declarations receive
exactly c-argdecl-indent spaces. The standard value is 5, resulting
in code like this:
char *
index (string, c)
char *string;
int c;
c-label-offset is the extra indentation given to a line that
contains a label, a case statement, or a default: statement. Its
standard value is -2, resulting in code like this
switch (c)
{
case 'x':
If c-label-offset were zero, the same code would be indented as
switch (c)
{
case 'x':
This example assumes that the other variables above also have their standard values.
I strongly recommend that you try out the indentation style produced by the standard settings of these variables, together with putting open braces on separate lines. You can see how it looks in all the C source files of GNU Emacs.
The Emacs parenthesis-matching feature is designed to show automatically how parentheses match in the text. Whenever you type a self-inserting character that is a closing delimiter, the cursor moves momentarily to the location of the matching opening delimiter, provided that is on the screen. If it is not on the screen, some text near it is displayed in the echo area. Either way, you can tell what grouping is being closed off.
In Lisp, automatic matching applies only to parentheses. In C, it applies to braces and brackets too. Emacs knows which characters to regard as matching delimiters based on the syntax table, which is set by the major mode. See section The Syntax Table.
If the opening delimiter and closing delimiter are mismatched--such as in `[x)'---a warning message is displayed in the echo area. The correct matches are specified in the syntax table.
Two variables control parenthesis match display. blink-matching-paren
turns the feature on or off; nil turns it off, but the default is
t to turn match display on. blink-matching-paren-distance
specifies how many characters back to search to find the matching opening
delimiter. If the match is not found in that far, scanning stops, and
nothing is displayed. This is to prevent scanning for the matching
delimiter from wasting lots of time when there is no match. The default
is 12,000.
When using X Windows, you can request a more powerful kind of
automatic parenthesis matching by loading the paren library.
To load it, type M-x load-library RET paren RET.
This library turns off the usual kind of matching parenthesis display
and substitutes another: whenever point is after a close parenthesis,
the close parenthesis and its matching open parenthesis are both
highlighted; otherwise, if point is before an open parenthesis, the
matching close parenthesis is highlighted. (There is no need to
highlight the open parenthesis after point because the cursor appears on
top of that character.)
Because comments are such an important part of programming, Emacs provides special commands for editing and inserting comments.
The comment commands insert, kill and align comments.
indent-for-comment).
set-comment-column).
kill-comment).
indent-new-comment-line).
The command that creates a comment is M-; (indent-for-comment).
If there is no comment already on the line, a new comment is created,
aligned at a specific column called the comment column. The comment
is created by inserting the string Emacs thinks comments should start with
(the value of comment-start; see below). Point is left after that
string. If the text of the line extends past the comment column, then the
indentation is done to a suitable boundary (usually, at least one space is
inserted). If the major mode has specified a string to terminate comments,
that is inserted after point, to keep the syntax valid.
M-; can also be used to align an existing comment. If a line already contains the string that starts comments, then M-; just moves point after it and re-indents it to the conventional place. Exception: comments starting in column 0 are not moved.
Some major modes have special rules for indenting certain kinds of comments in certain contexts. For example, in Lisp code, comments which start with two semicolons are indented as if they were lines of code, instead of at the comment column. Comments which start with three semicolons are supposed to start at the left margin. Emacs understands these conventions by indenting a double-semicolon comment using TAB, and by not changing the indentation of a triple-semicolon comment at all.
;; This function is just an example ;;; Here either two or three semicolons are appropriate. (defun foo (x) ;;; And now, the first part of the function: ;; The following line adds one. (1+ x)) ; This line adds one.
In C code, a comment preceded on its line by nothing but whitespace is indented like a line of code.
Even when an existing comment is properly aligned, M-; is still useful for moving directly to the start of the comment.
C-u - C-x ; (kill-comment) kills the comment on the current line,
if there is one. The indentation before the start of the comment is killed
as well. If there does not appear to be a comment in the line, nothing is
done. To reinsert the comment on another line, move to the end of that
line, do C-y, and then do M-; to realign it. Note that
C-u - C-x ; is not a distinct key; it is C-x ; (set-comment-column)
with a negative argument. That command is programmed so that when it
receives a negative argument it calls kill-comment. However,
kill-comment is a valid command which you could bind directly to a
key if you wanted to.
If you are typing a comment and wish to continue it on another line,
you can use the command M-LFD
(indent-new-comment-line). This terminates the comment you are
typing, creates a new blank line afterward, and begins a new comment
indented under the old one. When Auto Fill mode is on, going past the
fill column while typing a comment causes the comment to be continued in
just this fashion. If point is not at the end of the line when
M-LFD is typed, the text on the rest of the line becomes
part of the new comment line.
To turn existing lines into comment lines, use the M-x comment-region command. It adds comment delimiters to the lines that start in the region, thus commenting them out. With a negative argument, it does the opposite--it deletes comment delimiters from the lines in the region.
With a positive argument, comment-region duplicates the last
character of the comment start sequence it adds; the argument specifies
how many copies of the character to insert. Thus, in Lisp mode,
C-u 2 M-x comment-region adds `;;' to each line. Duplicating
the comment delimiter is a way of calling attention to the comment. It
can also affect how the comment is indented. In Lisp, for proper
indentation, you should use an argument of two, if between defuns, and
three, if within a defun.
The comment column is stored in the variable comment-column. You
can set it to a number explicitly. Alternatively, the command C-x ;
(set-comment-column) sets the comment column to the column point is
at. C-u C-x ; sets the comment column to match the last comment
before point in the buffer, and then does a M-; to align the
current line's comment under the previous one. Note that C-u - C-x ;
runs the function kill-comment as described above.
The variable comment-column is per-buffer: setting the variable
in the normal fashion affects only the current buffer, but there is a
default value which you can change with setq-default.
See section Local Variables. Many major modes initialize this variable for the
current buffer.
The comment commands recognize comments based on the regular
expression that is the value of the variable comment-start-skip.
Make sure this regexp does not match the null string. It may match more
than the comment starting delimiter in the strictest sense of the word;
for example, in C mode the value of the variable is "/\\*+
*", which matches extra stars and spaces after the `/*' itself.
(Note that `\\' is needed in Lisp syntax to include a `\' in
the string, which is needed to deny the first star its special meaning
in regexp syntax. See section Syntax of Regular Expressions.)
When a comment command makes a new comment, it inserts the value of
comment-start to begin it. The value of comment-end is
inserted after point, so that it will follow the text that you will insert
into the comment. In C mode, comment-start has the value
"/* " and comment-end has the value " */".
The variable comment-multi-line controls how M-LFD
(indent-new-comment-line) behaves when used inside a comment. If
comment-multi-line is nil, as it normally is, then the
comment on the starting line is terminated and a new comment is started
on the new following line. If comment-multi-line is not
nil, then the new following line is set up as part of the same
comment that was found on the starting line. This is done by not
inserting a terminator on the old line, and not inserting a starter on
the new line. In languages where multi-line comments work, the choice
of value for this variable is a matter of taste.
The variable comment-indent-function should contain a function
that will be called to compute the indentation for a newly inserted
comment or for aligning an existing comment. It is set differently by
various major modes. The function is called with no arguments, but with
point at the beginning of the comment, or at the end of a line if a new
comment is to be inserted. It should return the column in which the
comment ought to start. For example, in Lisp mode, the indent hook
function bases its decision on how many semicolons begin an existing
comment, and on the code in the preceding lines.
insert-parentheses).
move-over-close-and-reindent).
The commands M-( (insert-parentheses) and M-)
(move-over-close-and-reindent) are designed to facilitate a style
of editing which keeps parentheses balanced at all times. M-(
inserts a pair of parentheses, either together as in `()', or, if
given an argument, around the next several sexps. It leaves point after
the open parenthesis. The command M-) moves past the close
parenthesis, deleting any indentation preceding it (in this example
there is none), and indenting with LFD after it.
For example, instead of typing ( F O O ), you can type M-( F O O, which has the same effect except for leaving the cursor before the close parenthesis.
M-( may insert a space before the open parenthesis, depending on
the syntax class of the preceding character. Set
parens-dont-require-spaces to a non-nil value if you wish
to inhibit this.
Usually completion happens in the minibuffer. But one kind of completion is available in all buffers: completion for symbol names.
The character M-TAB runs a command to complete the partial symbol before point against the set of meaningful symbol names. Any additional characters determined by the partial name are inserted at point.
If the partial name in the buffer has more than one possible completion and they have no additional characters in common, a list of all possible completions is displayed in another window.
There are two ways of determining the set of legitimate symbol names
to complete against. In most major modes, this uses a tags table
(see section Tags Tables); the legitimate symbol names are the tag names listed in
the tags table file. The command which implements this is
complete-tag.
In Emacs-Lisp mode, the name space for completion normally consists of
nontrivial symbols present in Emacs--those that have function
definitions, values or properties. However, if there is an
open-parenthesis immediately before the beginning of the partial symbol,
only symbols with function definitions are considered as completions.
The command which implements this is lisp-complete-symbol.
In text mode and related modes, M-TAB completes words based on the spell-checker's dictionary. See section Checking and Correcting Spelling.
As you edit Lisp code to be run in Emacs, the commands C-h f
(describe-function) and C-h v (describe-variable) can
be used to print documentation of functions and variables that you want to
call. These commands use the minibuffer to read the name of a function or
variable to document, and display the documentation in a window.
For extra convenience, these commands provide default arguments based on the code in the neighborhood of point. C-h f sets the default to the function called in the innermost list containing point. C-h v uses the symbol name around or adjacent to point as its default.
Documentation on operating system commands, library functions and
system calls can be obtained with the M-x manual-entry command.
This reads a topic as an argument, and displays the "man page" on that
topic. manual-entry starts a background process that formats the
manual page, by running the man program. The result goes in a
buffer named `*man topic*'. These buffers use a special
major mode, Man mode, that facilitates scrolling and examining other
manual pages. For details, type C-h m while in a man page buffer.
Eventually the GNU project hopes to replace most man pages with better-organized manuals that you can browse with Info. See section Other Help Commands. Since this process is only partially completed, it is still useful to read manual pages.
The Emacs command C-x 4 a adds a new entry to the change log
file for the file you are editing
(add-change-log-entry-other-window).
A change log file contains a chronological record of when and why you have changed a program, consisting of a sequence of entries describing individual changes. Normally it is kept in a file called `ChangeLog' in the same directory as the file you are editing, or one of its parent directories. A single `ChangeLog' file can record changes for all the files in its directory and all its subdirectories.
A change log entry starts with a header line that contains your name,
your email address (taken from the variable user-mail-address),
and the current date and time. Aside from these header lines, every
line in the change log starts with a space or a tab. The bulk of the
entry consists of items, each of which starts with a line starting
with whitespace and a star. Here are two entries, each with two items:
@medbreak
Wed May 5 14:11:45 1993 Richard Stallman <rms@gnu.ai.mit.edu>
* man.el: Rename symbols `man-*' to `Man-*'.
(manual-entry): Make prompt string clearer.
* simple.el (blink-matching-paren-distance):
Change default to 12,000.
Tue May 4 12:42:19 1993 Richard Stallman <rms@gnu.ai.mit.edu>
* vc.el (minor-mode-map-alist): Don't use it if it's void.
(vc-cancel-version): Doc fix.
One entry can describe several changes; each change should have its own item. Normally there should be a blank line between items. When items are related (parts of the same change, in different places), group them by leaving no blank line between them. The second entry above contains two items grouped in this way.
C-x 4 a visits the change log file and creates a new entry unless the most recent entry is for today's date and your name. It also creates a new item for the current file. For many languages, it can even guess the name of the function or other object that was changed.
The change log file is visited in Change Log mode. In this major mode, each bunch of grouped items counts as one paragraph, and each entry is considered a page. This facilitates editing the entries. LFD and auto-fill indent each new line like the previous line; this is convenient for entering the contents of an entry.
A tags table is a description of how a multi-file program is broken up into files. It lists the names of the component files and the names and positions of the functions (or other named subunits) in each file. Grouping the related files makes it possible to search or replace through all the files with one command. Recording the function names and positions makes possible the M-. command which finds the definition of a function by looking up which of the files it is in.
Tags tables are stored in files called tags table files. The conventional name for a tags table file is `TAGS'.
Each entry in the tags table records the name of one tag, the name of the file that the tag is defined in (implicitly), and the position in that file of the tag's definition.
Just what names from the described files are recorded in the tags table depends on the programming language of the described file. They normally include all functions and subroutines, and may also include global variables, data types, and anything else convenient. Each name recorded is called a tag.
defun, any variable
defined with defvar or defconst, and in general the first
argument of any expression that starts with `(def' in column zero, is
a tag.
def or with a
construct whose name starts with `def'. They also include variables
set with set! at top level in the file.
-t is specified when the tags table is constructed. In C++ code,
member functions are also recognized.
\chapter,
\section, \subsection, \subsubsection, \eqno,
\label, \ref, \cite, \bibitem and
\typeout is a tag.
The etags program is used to create a tags table file. It knows
the syntax of several languages, as described in
the previous section.
Here is how to run etags:
etags inputfiles...
The etags program reads the specified files, and writes a tags table
named `TAGS' in the current working directory. etags
recognizes the language used in an input file based on its file name and
contents; there are no switches for specifying the language.
If the tags table data become outdated due to changes in the files described in the table, the way to update the tags table is the same way it was made in the first place. It is not necessary to do this often.
If the tags table fails to record a tag, or records it for the wrong file, then Emacs cannot possibly find its definition. However, if the position recorded in the tags table becomes a little bit wrong (due to some editing in the file that the tag definition is in), the only consequence is a slight delay in finding the tag. Even if the stored position is very wrong, Emacs will still find the tag, but it must search the entire file for it.
So you should update a tags table when you define new tags that you want to have listed, or when you move tag definitions from one file to another, or when changes become substantial. Normally there is no need to update the tags table after each edit, or even every day.
One tags table can effectively include another. Specify the included tags file name with the `-include=file' option when creating the file that is to include it. The latter file then acts as if it contained all the files specified in the included file, as well as the files it directly contains.
For a list of available etags options, type `etags --help'.
Emacs has at any time one selected tags table, and all the commands for working with tags tables use the selected one. To select a tags table, type M-x visit-tags-table, which reads the tags table file name as an argument. The name `TAGS' in the default directory is used as the default file name.
All this command does is store the file name in the variable
tags-file-name. Emacs does not actually read in the tags table
contents until you try to use them. Setting this variable yourself is just
as good as using visit-tags-table. The variable's initial value is
nil; that value tells all the commands for working with tags tables
that they must ask for a tags table file name to use.
Using visit-tags-table when a tags table is already loaded
gives you a choice: you can add the new tags table to the current list
of tags tables, or start a new list. The tags commands use all the tags
tables in the current list. If you start a new list, the new tags table
is used instead of others. If you add the new table to the
current list, it is used as well as the others. When the tags
commands scan the list of tags tables, they don't always start at the
beginning of the list; they start with the first tags table (if any)
that describes the current file, proceed from there to the end of the
list, and then scan from the beginning of the list until they have
covered all the tables in the list.
You can specify a precise list of tags tables by setting the variable
tags-table-list to a list of strings, like this:
(setq tags-table-list
'("~/emacs" "/usr/local/lib/emacs/src"))
This tells the tags commands to look at the `TAGS' files in your `~/emacs' directory and in the `/usr/local/lib/emacs/src' directory. The order depends on which file you are in and which tags table mentions that file, as explained above.
Do not set both tags-file-name and tags-table-list.
The most important thing that a tags table enables you to do is to find the definition of a specific tag.
find-tag).
find-tag-regexp).
find-tag-other-window).
find-tag-other-frame).
M-. (find-tag) is the command to find the definition of
a specified tag. It searches through the tags table for that tag, as a
string, and then uses the tags table info to determine the file that the
definition is in and the approximate character position in the file of
the definition. Then find-tag visits that file, moves point to
the approximate character position, and searches ever-increasing
distances away to find the tag definition.
If an empty argument is given (just type RET), the sexp in the buffer before or around point is used as the tag argument. See section Lists and Sexps, for info on sexps.
You don't need to give M-. the full name of the tag; a part
will do. This is because M-. finds tags in the table which
contain tag as a substring. However, it prefers an exact match
to a substring match. To find other tags that match the same
substring, give find-tag a numeric argument, as in C-u
M-.; this does not read a tag name, but continues searching the tags
table's text for another tag containing the same substring last used.
If you have a real META key, M-0 M-. is an easier
alternative to C-u M-..
Like most commands that can switch buffers, find-tag has a
variant that displays the new buffer in another window, and one that
makes a new frame for it. The former is C-x 4 ., which invokes
the command find-tag-other-window. The latter is C-x 5 .,
which invokes find-tag-other-frame.
To move back to places you've found tags recently, use C-u - M-.; more generally, M-. with a negative numeric argument. This command can take you to another buffer. C-x 4 . with a negative argument finds the previous tag location in another window.
The command C-M-. (find-tag-regexp) visits the tags that
match a specified regular expression. It is just like M-. except
that it does regexp matching instead of substring matching.
The commands in this section visit and search all the files listed in the selected tags table, one by one. For these commands, the tags table serves only to specify a sequence of files to search.
query-replace-regexp on each file in the selected tags table.
tags-loop-continue).
M-x tags-search reads a regexp using the minibuffer, then
searches for matches in all the files in the selected tags table, one
file at a time. It displays the name of the file being searched so you
can follow its progress. As soon as it finds an occurrence,
tags-search returns.
Having found one match, you probably want to find all the rest. To find
one more match, type M-, (tags-loop-continue) to resume the
tags-search. This searches the rest of the current buffer, followed
by the remaining files of the tags table.
M-x tags-query-replace performs a single
query-replace-regexp through all the files in the tags table. It
reads a regexp to search for and a string to replace with, just like
ordinary M-x query-replace-regexp. It searches much like M-x
tags-search, but repeatedly, processing matches according to your
input. See section Replacement Commands, for more information on query replace.
It is possible to get through all the files in the tags table with a single invocation of M-x tags-query-replace. But often it is useful to exit temporarily, which you can do with any input event that has no special query replace meaning. You can resume the query replace subsequently by typing M-,; this command resumes the last tags search or replace command that you did.
The commands in this section carry out much broader searches than the
find-tags family. The find-tags commands search only for
definitions of tags that match your substring or regexp. The commands
tags-search and tags-query-replace find every occurrence
of the regexp, as ordinary search commands and replace commands do in
the current buffer.
These commands create buffers only temporarily for the files that they have to search (those which are not already visited in Emacs buffers). Buffers in which no match is found are quickly killed; the others continue to exist.
It may have struck you that tags-search is a lot like
grep. You can also run grep itself as an inferior of
Emacs and have Emacs show you the matching lines one by one. This works
much like running a compilation; finding the source locations of the
grep matches works like finding the compilation errors.
See section Running Compilations under Emacs.
If you wish to process all the files in the selected tags table, but not in the specific ways that M-x tags-search and M-x tags-query-replace do, you can use M-x next-file to visit the files one by one.
M-x list-tags reads the name of one of the files described by the selected tags table, and displays a list of all the tags defined in that file. The "file name" argument is really just a string to compare against the names recorded in the tags table; it is read as a string rather than as a file name. Therefore, completion and defaulting are not available, and you must enter the string the same way it appears in the tags table. Do not include a directory as part of the file name unless the file name recorded in the tags table includes a directory.
M-x tags-apropos is like apropos for tags
(see section Apropos). It reads a regexp, then finds all the tags in the
selected tags table whose entries match that regexp, and displays the
tag names found.
You can also perform completion in the buffer on the name space of tag names in the current tags tables. See section Completion for Symbol Names.
It's not unusual for programmers to get their signals crossed and modify the same program in two different directions. To recover from this confusion, y