This chapter describes Emacs' advanced editing facilities. The following features are covered:
Not all Emacs commands are of the one- or two-character variety. All commands have long names composed of English words separated with dashes. This is because the long names are easier to remember and are more suggestive of the command actions than the one- or two-character short forms.
The commands with long names are known as extended commands or functions because they extend the set of one-character and two-character commands.
ESC-x (execute-extended-command)
Begins an extended command.
Extended commands are also called ESC-x commands, because they all start with the characters ESC-x. ESC-x is followed by the command's long, suggestive name (this is actually the name of the function to be called). Terminate the name of the function with a Return. For example, ESC-x delete-white-space Return calls the function delete-white-space.
We say that ESC-x FOO calls the function FOO. When documenting the individual extended commands, we call them functions to avoid confusion between them and the one-character or two-character commands. We also use ESC-x as a title for functions. The extended command is what you type, starting with ESC-x, and what the command does is call a function.
There are a great many functions in Emacs for you to call. They are described throughout this manual, according to what they do. This section is concerned only with extended commands in general.
When you type ESC-x, the cursor moves down to the Mini-buffer at the bottom of the screen. A colon is printed there, and when you type the command name it is echoed. You can use all the usual editing commands while in the Mini-buffer, except for the following:
These editing characters apply any time Emacs reads a line in the Mini-buffer, not just within ESC-x.
The colon which appears in the Mini-buffer is called a prompt. The prompt always tells you what sort of argument is required and what it is going to be used for; a colon means that you are using the command ESC-x, and that you should type the name of a function to be called.
You can abbreviate the name of the command, typing only as much as is needed to identify the command unambiguously. This is knows as command completion .
Using completion, you need type only part of the command name, and Emacs can then visibly fill in the rest, or as much as can be determined from the part you have typed.
You request completion by typing an Escape (or Do on Digital LK201 keyboards). For example, if you type ESC-x del Do the del expands to delete- because all command names that start with del continue with ete-.
If you ask for completion when there are several alternatives for the next character, a help window is displayed to show you the alternatives you can select. This window automatically disappears when the information is no longer relevant.
The Escape or Do keys are also used to terminate the command name and begin the arguments, but this only happens if the command name completes in full. In practice, the two meanings of Escape and Do do not conflict, because if the command name is not complete, it is ambiguous and Emacs does not accept it.
Typing the Help key in the middle of the command name prints a list of all the command names which begin with the text you have typed so far. You can then go on typing the name. If you type Help before typing any other commands, Emacs fills the help window with the names of all the available functions. The help window will be removed from the screen when the command name has been completely entered.
Note that if the EDTSIM or the LK201 packages have not been loaded, the default completion character is Escape and the default help character is a question mark (?)
Some functions can use numeric prefix arguments. Simply give the ESC-x command an argument and ESC-x will pass it along to the function which it calls.
Some functions require string arguments (sometimes called suffix arguments ). When a function's name has been completely filled in, the function will prompt for arguments. If information is to be selected from a list of alternatives, then completion will be enabled for those functions. Arguments should be separated with a Return when complete.
For example, the function describe-command prints the full documentation of a function whose name must be given as a string argument. Using completion to enter the command, you might type:
ESC-x desc Escape com Escape print-d Escape
to display information about the print-default function.
Subsystems and recursive editing levels are two states in which you are temporarily doing something other than editing the visited files as usual. For example, you might be editing a word's definition for the ESC-x describe-word-in-buffer command, or looking at a documentation file with INFO. Running another subprocess under Emacs can also be thought of as a sublevel.
A subsystem is an Emacs function which is an interactive program in its own right: it reads commands in a language of its own, and displays the results. You enter a subsystem by typing an Emacs command which invokes it, or by invoking it directly from DCL. Once entered, the subsystem runs until a specific command to exit the subsystem is typed. An example of an Emacs subsystem is INFO, the documentation reading program.
The commands understood by a subsystem are not like normal Emacs commands, because their purpose is something other than editing text. For example, INFO commands are designed for moving around in a tree-structured documentation file. In Emacs, most commands are control or escape sequences because printing characters insert themselves. In most subsystems, there is no insertion of text, so non-control characters can act as commands.
While you are inside a subsystem, the mode line usually gives the name of the subsystem, as well as other information optionally supplied by the subsystem. For example, INFO displays the current file name and node name.
Since each subsystem implements its own commands, we cannot guarantee anything about these commands. However, there are conventions as to the action of certain commands:
Scroll backward, like ESC-v in Emacs. | Backspace |
Scroll forward, like ^V in Emacs. | Space |
Exit from the subsystem. | q |
Begin an extended command, like ESC-x in Emacs. | x |
Display help on the subsystem's commands. | ? |
Note that not all of these commands necessarily exist in every subsystem. Try the ? key to see which commands a subsystem does define.
A recursive editing level is a state in which part of the execution of one command involves doing some editing. You may be editing the file you are working on, or you may be editing something totally different from what you were working on at top level. Recursive editing levels are indicated in the mode line by square brackets.
For example, the command ^U-^X-^D calls the function describe-word-in-buffer and lets you edit an existing word's description. During the execution of this command, you enter a recursive editing level in which you alter or create the new definition. While this is going on, the mode line contains [Edit description word: word xxx] to inform you that you are in a recursive editing level. When you exit the recursive editing level, the describe-word-in-buffer command continues its work by inserting the entry into the subr-names database. Only then is the original ESC-x describe-word-in-buffer command finished.
Alternatively, you can abort the recursive editing level, which gets you out of the ESC-x describe-word-in-buffer command and back to top level, without allowing the command to finish.
A recursive editing level differs from a subsystem in that the commands are ordinary Emacs commands (although a few may be slightly modified), whereas a subsystem defines its own commands. The text you edit inside a recursive editing level depends on the command which invoked the recursive editing level.
Exit from Emacs or from a recursive editing level. | ^C |
Return to the top level, aborting all recursive edits, packages and subsystems. | ESC-x top-level |
Temporarily returns to the parent process, if there is one. The paused Emacs may be re-started at a later time. | ESC-x pause-emacs |
The general Emacs exit command is ^C. This command is used to exit from a recursive editing level back to the top level of Emacs, and to exit from Emacs at top level.
We cannot say in general how to exit a subsystem, since each subsystem defines its own command language. The convention is to use the Q key.
You can exit from Emacs back to the parent process at any time (even from within a recursive editing level) using the ESC-x pause-emacs command. If you use this command while inside a recursive editing level, when Emacs is re-entered you will still be inside the recursive editing level.
Exiting Emacs does not normally save visited files, because it is not always true that you exit Emacs only when you have finished editing. If you want files saved, you must use ^X-^M before exiting. However, if modified buffers exist when you exit, Emacs will ask you to confirm that you wish to discard the edits you have made.
Several variables are provided that allow you to modify the default action when you enter and exit Emacs. These are:
To do this... | ...set this variable |
Execute a function to be executed when Emacs is initially entered. | enter-emacs-hook |
Execute a function when Emacs finally exits. | exit-emacs-hook |
Execute a function when Emacs re-starts after an ESC-x pause-emacs command. | return-to-emacs-hook |
Executed a function when ESC-x pause-emacs is used. | leave-emacs-hook |
An alternative to exiting Emacs or using ESC-x pause-emacs is to create another subprocess under Emacs. You can probably do in a subprocess whatever you would have done after exiting Emacs, and the subprocess will not interfere with Emacs' operation. Use the ESC-x return-to-monitor command to start a subprocess, then use the DCL LOGOUT command to return to Emacs.
All symbols and un-confined process logical names are propagated to the subprocess.
In general, a command which processes an arbitrary part of the buffer must know where to start and where to stop. In Emacs, such commands usually operate on the text between dot and mark -- this range of text is called the region . To specify a region, you position dot at one end of the region, and set mark at the other end. It does not matter which end is positioned first, or which end comes earlier in the text. Here are some commands for manipulating the mark:
Sets the mark at the location of dot. | ^@ or Select (set-mark) |
Exchange dot and mark. | ^X-^X (exchange-dot-and-mark) |
Set dot and mark around the most recently found string or string partition. | ESC-x region-around-match |
Delete the current mark. | ^X-^@ (unset-mark) |
For example, if you want to convert part of the buffer to upper-case, you can use the ESC-x case-region-upper command, which operates on the text in the region. You first go to the beginning of the text to be altered, set the mark there, move to the end, and then type ESC-x case-region-upper. Or, you can set the mark at the end of the text, move to the beginning, and then type ESC-x case-region-upper.
The most common way to set the mark is with the ^@ or Select command. This sets the mark at the current location of dot. You can then move dot away, leaving the mark behind. The easiest way to type the ^@ command on Digital keyboards is to press and hold the Ctrl key and simultaneously press the Space bar.
Emacs allows you to see the currently selected region by highlighting the text between the mark and dot in buffers with the highlight-region variable set.
You can always see where the mark is with the command ^X-^X which puts the mark where dot is and dot where the mark was. The extent of the region is unchanged, but the cursor and dot are now at the previous location of the mark.
^X-^X is also useful when you are satisfied with the location of dot but want to move the mark; type ^X-^X to put dot where the mark currently is, then you can move it. A second use of ^X-^X, if necessary, puts the mark at the new location with dot back at its original position.
If you have set a mark and wish to remove it, use the command unset-mark by typing ^X-^@. The mark is removed, and dot remains unchanged. This is useful where a highlighted region may distract you when you have finished with it.
The commonest way to move or copy text in Emacs is to delete it, and then restore it in one or more places.
Most commands which erase text from the buffer save it somewhere so that you can retrieve it if you change your mind, or if you want to move or copy it to other parts of the buffer. The delete commands that do not save the text include ^D and Delete, which delete only one character at a time, and those commands that delete only spaces or line separators. Commands that can destroy significant amounts of non-trivial data generally save the text. If you use any delete command by mistake, you can use the ^X-^U command to undo it.
The text deletion commands are:
Delete the next character. | ^D (delete-next-character) |
Delete the previous character. | Delete (delete-previous-character) |
Delete the rest of the line or one or more lines. | ^K (kill-to-end-of-line) |
Delete the region. | ^W (delete-to-killbuffer) |
Delete the next word. | ESC-d (delete-next-word) |
Delete the previous word. | ESC-h (delete-previous-word) |
The most basic delete commands are ^D and Delete. ^D deletes the character the cursor is over. The cursor does not move. Delete deletes the character before the cursor, and moves the cursor back one character. Line separators act like single characters when they are deleted.
The ^W command is a general delete command. This command deletes everything between dot and mark. With this command, you can delete any contiguous characters if you first set the mark at one end of the character string, then move to the other end and use ^W. The deleted text is saved in a buffer called Kill buffer.
The simplest delete command is ^K. If given at the beginning of a line, it deletes all the text on the line leaving it blank. If given on a blank line, the blank line is deleted. As a consequence, if you go to the front of a non-blank line and type two ^K s, the line disappears completely.
More generally, ^K deletes from dot up to the end of the current line, unless it is at the end of a line. When dot is at the end of a line, ^K deletes the line separator following the line, thus joining the next line with the current line.
^K moves the text it deletes into Kill buffer. This is the same buffer that ^W uses, so ^K and ^W cannot be used at the same time as each command erases the data in Kill buffer first. However, successive uses of the ^K command add the newly-deleted data to the end of Kill buffer (the command only erases Kill buffer when the previous command was not a ^K). So, if you wish to move a region to another place in the buffer without disturbing dot, use a number of ^K s, or provide the ^K command with a prefix argument.
Insert the last-deleted text. | ^Y (yank-from-killbuffer) |
Undeleting is retrieving text which has been deleted. The usual way to move or copy text is to delete it, then undelete it one or more times.
The ^Y command inserts the entire contents of Kill buffer into the current buffer at the location of dot.
Text is usually copied or moved by first deleting it and then undeleting it. There are other methods that are useful for copying one block of text to many places, or for copying many scattered blocks of text into one place. You can accumulate blocks of text from scattered locations either into a buffer or into a file.
To append blocks of text into a buffer, use the command ESC-x append-region-to-buffer, which inserts a copy of the region into the specified buffer at the location of dot in that buffer. If there is no buffer with the name you specify, the buffer is created.
Dot in the specified buffer is left at the end of the copied text, so successive uses of append-region-to-buffer accumulate the text in the specified buffer.
You can retrieve the accumulated text from that buffer with ESC-x yank-buffer. This inserts a copy of the text in the specified buffer into the current buffer. You can also select the other buffer for editing.
Rather than accumulating text in an Emacs buffer, you can append text directly to a disk file with the command ESC-x append-to-file. This command adds the text of the region to the end of the specified file. The file is modified immediately on disk. This command is normally used with files that are not being visited in Emacs.
This section describes commands that are especially useful when you catch a mistake in your text just after you have made it, or change your mind while composing.
Delete the previous character. | Delete (delete-previous-character) |
Delete the previous word. | ESC-h (delete-previous-word) |
Transpose the last two characters. | ^T (transpose-characters) |
Undo the last sequence of commands that affected buffers. | ^X-^U (undo) |
The Delete command is the most important correction command. When used with self-inserting characters, it can be thought of as cancelling the last character typed.
When your mistake is longer than a couple of characters, it might be more convenient to use ESC-h. ESC-h deletes back to the start of the last word.
ESC-h is often useful even when you have typed only a few incorrect characters, or if you know you are confused in your typing and are not sure exactly what you typed. In such cases, you cannot correct with Delete except by looking at the screen to see what you did. It requires less thought to delete the whole word and start over again, and is quicker if the system is heavily loaded.
The common error of transposing two characters can be corrected with the ^T command when the characters are adjacent. ^T transposes the two characters preceding dot, so if you catch your transposition error right away, you can correct it with a ^T. If you do not catch it so quickly, you must move the cursor back to 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 moving to the correct position.
A very common error is to type words in the wrong case. As this is such a common error, the word case-conversion commands ESC-l, ESC-u and ESC-^ have a special feature: they do not move the cursor. As soon as you see you have mis-typed the last word, you can simply change its case and go on. See Case Conversion Commands for details on using the case-conversion commands.
The basic unit of stored data is the file. Each document lives in its own file. To edit a document, you must tell Emacs the name of the file that contains it. This is called visiting the file. To make your changes to the file permanent on disk, you must save the file. Emacs also has facilities for deleting files conveniently.
For convenience, all file operation commands are prefixed with ^X.
Visit a file. | ^X-^V (visit-file) |
Save the current file to disk. | ^X-^s (write-current-file) |
Visiting a file means copying the file into Emacs where you can edit it. Emacs remembers the name of the file you visited. When you visit a file, a new buffer is created for the file; the buffer name is derived from the file name you visited. When you visit a file, the buffer containing the file is displayed in one of the windows on the screen. If only a small number of windows are currently displayed, a new window may be created for the buffer. The fully-expanded name of the file you are visiting is visible in the mode line when you are at top level.
The changes you make with Emacs are made to a copy of the file inside Emacs, not to the file itself. The changed text is not made permanent until you save it in a file. The first time you change the text, an asterisk appears in the mode line. This indicates that the text contains fresh changes which will be lost unless you save them.
To visit a file, use the command ^X-^V. Follow the command with the name of the file you wish to visit, terminated by a Return. Emacs uses the standard VMS defaulting mechanism when accessing files. You can abort the command while it is asking for a file name by typing ^G; you can also edit the filename with the standard editing commands. File name completion is enabled. See Command Completion for more information on name completion.
When you wish to save the file and make your changes permanent, type ^X-^s. After the save is finished, ^X-^s prints Wrote: filename in the Mini-buffer, where filename is the name of the file written.
If you want to create a file, just visit it. Emacs prints New File: filename in the Mini-buffer, but apart from that, behaves exactly as if you had visited an existing empty file. If you make any changes and save them, the file is created. If you visit a non-existent file unintentionally (because you typed the wrong file name), go ahead and visit the file you meant to visit. If you do not modify or save the unwanted file, it is not created.
If you visit one file and then visit another which would use the same buffer name, Emacs asks you what buffer to use for the new file. You can answer with a Return, and the old buffer's contents will be destroyed, or you can type the name of a buffer to use.
You can also set the variable ask-about-buffer-names so that Emacs automatically appends a sequence number to the buffer used. For example, if you visit file A.B, Emacs creates buffer a.b. With ask-about-buffer-names set to 1, if you then visit file SYS$SYSTEM:A.B, Emacs will use buffer a.b<2>), and so on.
Emacs has extended commands for performing many other operations on files.
ESC-x view-file
Scans or reads a file by sequential screensful without visiting the file. It enters a subsystem in which you type a Space to see the next screenful, or a Backspace to see the previous screenful. Typing any other character exits the command.
Write the contents of the current buffer into the file specified, and then visits that file. This can be thought of as a way of changing the name of the file you are visiting. | ^X-^W (write-named-file) |
Insert the contents of the specified file into the buffer at dot, leaving dot at the beginning of the inserted text. | ^X-^I (insert-file) |
Append the current buffer to the end of a nominated file. | ESC-x append-to-file |
Delete the specified file. | ESC-x unlink-file |
Write all file buffers that have been modified since they were last visited and deletes the appropriate checkpoint and/or journal files. | ^X-^M (write-modified-files) |
Write all file buffers that have been modified and then exits Emacs (or a recursive edit level). | ^X-^F (write-file-exit) |
The variable current-buffer-file-name contains the name of the file to which the current buffer is associated (if there is one). You can change the name by setting this variable to the required file name.
Emacs offers two features that protect against losing changes to files that you are editing. These features are called checkpointing and journalling.
When checkpointing is enabled, Emacs saves your buffers from time-to-time when a certain number of keystrokes have been made. The buffers are written automatically, but you can also force Emacs to checkpoint at any time you wish. Checkpointing prevents you from losing more than a limited amount of work when a disaster occurs.
When journalling is enabled, Emacs saves all the insertions and deletions made to your buffers in a journal file . The changes are saved to the journal file at the same time as you make them to the proper file.
Each method has its advantages and disadvantages. You will notice that it can take a long time to write the checkpoint file for a large file, since Emacs writes out the whole file every time it checkpoints. On the other hand, journalling only writes out the changes that you have made, which is much faster.
Journalling is at a disadvantage when you use complex commands which make many changes to the buffer. When this happens, many journal records must be written to the journal file.
If you want Emacs to checkpoint, you must set the variable checkpoint-frequency to the number of keystrokes you want to strike between checkpoints. If checkpoint-frequency is zero, checkpointing is disabled for all buffers. By default checkpointing is set to occur every 300 keystrokes.
Each time you visit a file, no matter how, checkpointing is turned on for the created buffer if checkpoint-frequency is non-zero. Once you have visited a file, you can turn checkpointing on or off by setting the variable current-buffer-checkpointable to 1 or 0. You can tell if a buffer has checkpointing switched on and if checkpointing is enabled as the minor mode string Checkpoint will be displayed in the buffer's mode line.
If a checkpoint occurs while the activity indicator is being used, the checkpoint activity is indicated by a c in the bottom-left hand corner of the screen. When the checkpoint is complete, this will change back to the character displayed before the checkpoint started.
When a checkpoint occurs and the activity indicator is switched off, Checkpointing... is printed in the Mini-buffer. When all modified files have been checkpointed, Emacs displays Checkpointing... done. If an error is detected during the checkpoint, error. is displayed instead of done.
The action of saving each modified buffer occurs because the default checkpoint action is to call the function checkpoint-buffers. When checkpointing runs, it calls the function whose name is in the variable checkpoint-hook. The default value for checkpoint-hook is the function checkpoint-buffers.
checkpoint-buffers writes each buffer to its own checkpoint file. The file used has the same file name as the buffer name with an extension of .CKP All checkpoint files are written to the default directory by default. For non-file buffers, the buffer name is used and the extension .CKP is added to make a file name; if this results in a file name with incorrect syntax, CHECKPNT.CKP is used as the file name.
If you do not want checkpoint files written to the default directory, you can define the logical name Emacs_CHECKPOINT as the location for your checkpoint files. If this logical name is defined before Emacs is started, Emacs will write all checkpoint files to this directory rather than to the default directory.
When it is time to recover files after a system crash, simply rename the checkpoint files to their original file names.
Emacs deletes a checkpoint file whenever the proper file is saved. It also deletes checkpoint files when Emacs exits if the variable unlink-checkpoint-files is set.
If you want Emacs to journal, you must set the variable journal-frequency to the number of seconds you want Emacs to wait before writing out journal records. If journal-frequency is zero, journalling is disabled for all buffers. When Emacs starts up, checkpointing is enabled and journalling is disabled.
Each time you visit a file, no matter how, journalling is turned on for the created buffer if journal-frequency is non-zero. Once you have visited a file, you can turn journalling on or off by setting the current-buffer-journalled variable. You can tell if a buffer has journalling switched on and whether journalling is enabled as the mode line for the buffer will contain the minor mode string Journal.
If journalling is writing to the journal file and the activity indicator is being used, the journal activity is indicated by a j in the bottom left hand corner of the screen. When the journalling is complete, this will change back to the character displayed before the journalling started. However, it is rare that you will see the j, because journalling is very fast.
When it is time to recover files after a system crash, simply use the journal-recover command, specifying the name of the journal file to recover.
All the journal files that Emacs writes are kept in the directory Emacs_JOURNAL: For each buffer that had journalling enabled and had not been saved, there will be a journal file in Emacs_JOURNAL:.
For buffers with associated files, the journal name will be based on the file name. For example, the file LOGIN.COM will have a journal file named LOGIN.COM_Emacs_JOURNAL.
For buffers without associated files, the journal has a slightly different name. For example, the buffer Kill buffer will have a journal called KILL_BUFFER.BUFFER_Emacs_JOURNAL0000.
journal-recover prompts for the name of the journal file, which must be in Emacs_JOURNAL:. Emacs will check that the journal file is valid before attempting to apply it. For a file, Emacs checks that the version number of the file is the same as the journal was recorded for. For a buffer, Emacs checks that the buffer does not exist. These checks ensure that using journal-recover will not damage your data.
Emacs deletes a journal file whenever the proper file is saved. Journal files are also deleted when Emacs exits.
Each operating systems has different end-of-line delimiters for text files. Emacs supports the end-of-line styles for Unix, Windows and Machintosh.
Emacs, by default, will save a file using the same end-of-line style it had when read in.
The end-of-line style is displayed in the status bar. The indicator will be:
Emacs uses the following variables to support the editing of files:
current-buffer-end-of-line-style | buffer-specific variable containing a string value describing the end-of-line style of the file associated with the current buffer. |
default-buffer-end-of-line-style | contains a string value indicating the record format in which new files written by Emacs should be created. |
override-end-of-line-style | contains a string value describing the format in which to write out all new files, overriding the setting of current-buffer-end-of-line-style. The default value is to not override. |
Every buffer created by Emacs is assigned the buffer-specific variable current-buffer-end-of-line-style. This variable contains a string value which describes the end-of-file style of the file associated with each buffer. When Emacs visits an existing file, it determines the file's end-of-line style and sets the current-buffer-end-of-line-style variable accordingly. The values that this variable can take are described below.
File Type | current-buffer-end-of-line-style |
---|---|
Windows and MS-DOS text files | crlf |
Unix (Linux) text files | lf |
Macintosh text files | cr |
Binary files | binary |
When Emacs writes a buffer out to a file, the new file is created with the end-of-line style described by the current-buffer-end-of-line-style variable.
When you visit a new file, Emacs uses the default-buffer-end-of-line-style variable to set the equivalent buffer-specific variable. The default value is appropiate for your operating system.
You can override the setting of current-buffer-end-of-line-style and force files to be written in a particular style by setting the override-end-of-line-style variable. The default setting for this variable is none, which means do not override. You can set override-end-of-line-style to any of the supported end-of-line styles listed above. For example, to force all files to be written in lf format, use the following code:
(setq override-end-of-line-style "lf")
Since only part of a large buffer can fit on the screen, Emacs tries to show the part of the buffer that is likely to be most interesting. The display control commands allow you to tell Emacs that you want to see a different part of the buffer.
Clear and re-displays the screen. | ^L (redraw-display) |
Scroll forward one line. | ^Z (scroll-one-line-up) |
Scroll backward one line. | ESC-z (scroll-one-line-down) |
Move the line in which dot is located to the top of the current window. | ESC-! (line-to-top-of-window) |
Scroll one column from the left-hand side of the screen. | ESC-x scroll-one-column-left |
Scroll one column from the right-hand side of the screen. | ESC-x scroll-one-column-right |
Scroll the current column to the left of the screen. | ESC-@ (column-to-left-of-window) |
Move to the next page. | ^V or Next Screen (next-page) |
Move back a page. | ESC-v or Prev Screen (previous-page) |
The terminal screen is rarely large enough to display all of your file. If the whole buffer does not fit on the screen, Emacs displays a contiguous portion of the buffer that always contains dot. Emacs continues to display approximately the same portion of the buffer until dot moves outside of the displayed portion; Emacs then chooses a new portion centred around the new location of dot. This is Emacs' guess as to what you are most interested in seeing. If Emacs' guess is wrong, you can use the display control commands to see a different portion. The finite area of screen through which you can see part of the buffer is called a window . Emacs can display many windows on the screen; the maximum number of displayable windows is determined by the number of lines on the screen.
When Emacs chooses a new window position, it always tries to place dot half-way down the buffer's window. This is controlled by the variable scroll-step, whose value is the number of lines to automatically move the window. However, if the end of the buffer is on the screen, Emacs tries to leave as little as possible of the screen blank beneath it, so that the screen space is not wasted.
The basic display control command is ^L. This command clears the screen and re-draws it from internal information.
The vertical scrolling commands ^Z and ESC-z let you move a whole window up or down a few lines. ^Z with an argument shows you the specified number of lines at the bottom of the window, moving the text but not moving dot unless it moves out of the window. ^Z with a negative argument shows you more lines at the top of the window, as does ESC-z with a positive argument.
The horizontal scrolling commands let you move the whole window left or right by a few columns. This lets you view buffers with lines that are longer than your screen's width. The most useful of these commands is column-to-left-of-window. You can move dot in a line until you decide where the new left-hand side of the screen should be, then use the ESC-@ command to move the window to the selected column. When you want the window back to the left side of the buffer, go to the beginning of the line with ^A and use column-to-left-of-window again.
To read the buffer a window-full at a time, use the ^V or Next Screen command with no argument. This moves the start of the window 4/5th's of a screen further down the buffer. Dot will remain where it was unless it moves out of the window. Thus, each ^V command displays the next window-full, except for two lines of overlap to provide continuity. To move backward, use ESC-v without an argument, which moves a window-full backwards.
Scanning by screen-fulls through the buffer for some distance is most conveniently done with the ESC-x view-buffer command. This command enters a simple subsystem in which Space moves a screen-full forward and Backspace moves a screen-full backward. The Return character exits, leaving dot centred in whatever part of the buffer was visible. Any other character exits and returns dot to its former location, and is then executed as a command. view-buffer can be used to view another buffer by giving the buffer's name as a string argument.
Emacs can contain a large number of buffers, each containing text. At any time, only one buffer can be selected and available for editing, but it is not difficult to switch to a different buffer. Each buffer individually remembers which file it is visiting, which modes are enabled, and whether there are any changes that need saving. Buffer manipulation commands are all prefixed with ^X.
Select or create a buffer in the current window. | ^X-b (switch-to-buffer) |
List the existing buffers. | ^X-^B (list-buffers) |
Delete the nominated buffer. | ESC-x delete-buffer |
Switch to the specified buffer using a different window. | ESC-x pop-to-buffer |
Each buffer in Emacs has a single name which normally does not change. A buffer's name can be any length. The name of a buffer, and the name of the file visited in it, are visible in the mode line when you are at top level.
To create a new buffer, you need only think of a name for it (say, FOO) and then type ^X-b FOO which is the command ^X-b followed by the buffer name. This makes a new, empty buffer and selects it for editing. The new buffer is not visiting any file and is called a scratch buffer. Each buffer has its own major mode; a new buffer's major mode is always Normal Mode.
To return to buffer FOO later after having switched to another buffer, the same command ^X-b FOO is used, since ^X-b can tell whether or not a buffer named FOO already exists.
^X-b changes the buffer associated with the current window. You can use ESC-x pop-to-buffer to use another window and select a new buffer.
To get a list of all existing buffers, type ^X-^B. Each buffer's name, size in characters, buffer type (Scr for scratch, File for file and Macro for macro), major and minor modes, and visited file are all displayed. An M indicates a modified buffer which contains changes that have not been saved. C, A and R indicate that checkpointing, Abbreviation Mode and replace mode are in effect for the buffer.
The variable current-buffer-name contains the name of the currently selected buffer, and can be set to change the name of the buffer. Name collisions are detected and an error message is generated when such collisions occur.
The commands ESC-x append-region-to-buffer and ESC-x yank-buffer can be used to copy text from one buffer to another. See Deleting and Moving Text for details on deleting and moving text.
After you use an Emacs session for a while, it may fill up with buffers which you no longer need. Eventually, you can reach a point where trying to create any more buffers results in an error message.
You can delete buffers using the ESC-x delete-buffer command. If you delete the current buffer in any way, Emacs will automatically select a new buffer as the current buffer. If other buffers are displayed on the screen, Emacs will select one of these buffers and will make it the current buffer. If you delete the last exisiting buffer, Emacs will automatically create a buffer called main and will make main the current buffer.
If you attempt to delete a buffer that has un-saved modifications, Emacs asks you to verify that you wish to discard the changes you have made.
Emacs allows you to split the screen into many windows and use them to display parts of any buffer. The number of windows that can be fitted on the screen is dependent on the number of lines on the displaying terminal. Each window must be at least two lines long, one line for the text portion and the other line for the window's mode line. So, for a 24-line VT220 terminal, the maximum number of displayable windows is 11.
The following commands are available for manipulating windows:
Split the current window horizontally into two windows. | ^X-2 (split-current-window) |
Split the current window vertically into two windows. | ^X-3 (split-current-window-vertically) |
Remove all other windows. | ^X-1 (delete-other-windows) |
Move dot to the window below the current window. | ^X-n (next-window) |
Move dot to the window above the current window. | ^X-p (previous-window) |
Enlarge the current window. | ^X-z (enlarge-window) |
Shrink the current window. | ^X-^Z (shrink-window) |
Reduce the width of the current window. | ESC-x narrow-window |
Increase the width of the current window. | ESC-x widen-window |
Delete the current window. | ^X-d (delete-window) |
Scroll the window below the current window. | ESC-^V (page-next-window) |
The command ^X-2 divides the current window into two equally-sized windows. The two windows will be connected to the same buffer, so that the text of that buffer around dot will be displayed in both windows.
^X-3 also divides the current window into two equally-sized windows, but the two windows are placed side-by-side instead of one above the other as is done by ^X-2.
To return to viewing only one window, use the command ^X-1. The current window expands to fill the whole screen, and all other windows disappear.
^X-d deletes the current window and re-positions dot in the window directly above. If only one window is on the screen, buffer Main is popped onto the screen.
While you have more than one window displayed on the screen, you can use ^X-n and ^X-p to switch between windows. If you attempt to move to the next window from the last window on the screen, Emacs considers the next window to be the window at the top of the screen. Similarly, if you attempt to move to the previous window when dot is in the top window, Emacs moves dot to the bottom window.
If the current buffer and window is the Mini-buffer at the bottom of the screen, then this window, too, is considered to be in the ring of windows displayed on the screen.
Often you will be editing one window while using another just for reference. The command ESC-^V is very useful in such cases -- it scrolls the next window without switching to it and switching back. It scrolls the same way ^V does: with no argument, 4/5th's of the window up; with an argument n, n pages up (or down when n is negative).
When you split a window, the space for the old window will be divided evenly between the two windows. You can redistribute screen space between the windows with the ^X-z and ^X-^Z commands. These make the currently selected window become one line bigger or smaller respectively (or as many lines as is specified with a numeric argument).
Narrowing means focussing-in on one portion of a buffer, making the rest of the buffer temporarily invisible and inaccessible.
Narrow down to the region between dot and mark. | ESC-x narrow-region |
Widens to view the entire buffer. | ESC-x widen-region |
When you have narrowed down to a part of the buffer, the narrowed part appears to be all there is. You cannot see the rest of the buffer; you cannot move into it, since motion commands will not move outside of the narrowed part; you cannot change it in any way. However, it has not been deleted, and if you save the file, all the invisible text will be saved.
Narrowing can be used to concentrate on a single subroutine or paragraph by eliminating clutter. Narrowing is also useful when you want to restrict the range of operation of commands such as replace commands.
The primary narrowing command is ESC-x narrow-region. It sets the virtual buffer boundaries at dot and mark, so that only the text that was between dot and mark remains accessible. Dot and mark do not change.
Use the ESC-x widen-region command to remove the narrowing. This makes all the text in the buffer accessible again.
Like other text editors, Emacs has commands that search for an occurrence of a text string. The Emacs search commands are unusual in that they can be normal text searches or regular expression pattern matches.
Regular expression searching allows complex patterns to be specified and searched for, with the ability to partition matched strings for later reference and substitution.
The ordinary searching commands are:
Search forward. | ^S (search-forward) |
Search backward. | ^R (search-reverse) |
^S prompts for a string, and search through the buffer starting at dot for the specified string. If no string is specified, search-forward searches for the next occurrence of the last search string.
Generally, Emacs looks for the string exactly as you typed it. So, if you search for FOO then FOO in the text will match, but Foo or foo will not. However, if you set the variable case-fold-search to 1, all searches will make upper- and lowercase letters appear the same.
Regular expression searching provides a powerful pattern-matching facility with optional partitioning of the pattern for later substitution.
The regular expression search commands are:
Search for a pattern match forwards. | ESC-x ere-search-forward |
Search for a pattern match backwards. | ESC-x ere-search-reverse |
Both these commands expect an extended regular expression pattern for which to search. The pattern is interpreted and matched against text according to the following rules:
The function ere-looking-at returns 1 or 0 depending on whether the specified regular expression follows dot.
Note: The functions re-search-forward, re-search-reverse and looking-at implement a less powerful regular expression language that is deprecated in favor of the simpler to use and more powerful ere-search-forward, ere-search-reverse and ere-looking-at functions.
Emacs has a normal text replacement function similar to that found in most text editors. Emacs also has a query replace operation which asks you, for each occurrence of the search string, whether or not to replace it. Emacs also allows you to use regular expressions in replace commands.
To replace every instance of FOO after dot with BAR, you can type ESC-r FOO BAR. This runs the function replace-string. Replacement occurs only after dot, so if you want to cover the whole buffer you must go to the beginning of the buffer first. Replacement continues to the end of the buffer, but you can restrict the scope of the replace command using narrowing. See Narrowing for details on narrowing commands.
Unless the variable replace-case is zero, ESC-r tries to preserve case. For example, if you give both foo and bar in lower case, and if a particular FOO is found with a capital initial or all capitalized, the BAR which replaces it will be given the same case pattern. Thus, ESC-r foo bar would replace foo with bar, Foo with Bar and FOO with BAR. If replace-case is zero, the replacement string is inserted with the case you used when you typed it.
If case-fold-search is zero, the string to be replaced is found only when it has the same case as the string you typed.
If you want to change only some of the occurrences of a string but not all, you cannot use an ordinary replace command. Instead, use ESC-q. This displays each occurrence of the matched pattern and waits for you to confirm whether or not you want to replace it. The characters you can type when you are shown an occurrence of the original string are:
Replaces the string. | Space |
Skips to the next match without replacing this match. | n |
Replaces this match and displays the result. You are then asked for another input character. Since the replacement has already been made, Delete and Space are equivalent. | Comma |
Exits the query replace command without doing any more replacements. | ^G or q |
Replaces this match, then stops the query replace command. | Period |
Replaces all remaining matches without asking for further confirmations. | ! |
Enters a recursive editing level so that you can edit the occurrence rather than just replace it. When you are done, exit the recursive editing level with ^C and the next occurrence will be located. | r |
Any other character solicits a help display to remind you of the available options.
The Emacs regular expression replace commands are:
Perform a replace operation using regular expression search and replacement strings. | ESC-x ere-replace-string |
Perform a query replace operation using regular expression search and replacement strings. | ESC-x ere-query-replace-string |
An extra feature of the ere-replace-string and ere-query-replace-string commands is the ability to insert portions of the matched string as part of the replacement.
Regular expression search strings may also be partitioned into a number of regular-expression substrings using the ( and ) delimiters. Each of the strings that matches one of the subpatterns may be separately inserted into the replacement text. You specify which match to insert by using \n. n is the position of the string to insert, starting from the left-hand side in the pattern. The first bracketed pattern is designated as string 1. For example, if you search for abc(.*)ghi(.*) and specify a replacement string of \2\1 and apply these regular expression to the text abcdefghijkl, the replacement text will be jkldef.
Note: The functions re-replace-string and re-query-replace-string implement a less powerful regular expression language that is deprecated in favor of the simpler to use and more powerful ere-replace-string and ere-query-replace-string functions.
Abbreviation Mode allows you to abbreviate text with a single word. Emacs expands the abbreviation automatically as soon as you have finished typing the abbreviation.
Abbreviations are also useful for correcting commonly misspelled or mis-typed words (abbreviation thier could expand to their), and for upper-casing words like Emacs (abbreviation emacs could expand to Emacs).
The Abbreviation Mode commands are:
Define an abbreviation and expansion and puts them in the global abbreviation table. | ESC-x define-global-abbrev |
Define an abbreviation and expansion and puts them in the current buffer's local abbreviation table. | ESC-x define-local-abbrev |
Read a file of abbreviations, and merges their definitions into the existing set of abbreviation tables. Duplicate entries over-write existing entries in existing abbreviation tables. | ESC-x read-abbrev-file |
Write the abbreviations defined by all the abbreviation tables into a file for later reading. | ESC-x write-abbrev-file |
Associate a named abbreviation table as the current buffer's local abbreviation table. | ESC-x use-abbrev-table |
Check to see if a string will be expanded, and returns the expansion for the current buffer. | ESC-x test-abbrev-expand |
To use Abbreviation Mode, define a global or local abbreviation using either of the commands ESC-x define-local-abbrev or ESC-x define-global-abbrev. Abbreviation Mode is controlled by a variable called abbrev-mode. When abbrev-mode is non-zero, abbreviations will be expanded. Defining an abbreviation forces abbrev-mode to be set.
In writing this documentation, we could have defined am to be an abbreviation for abbrev mode. After typing just the letters am, we see just that, am; but if we then finish the word by typing space or period or any other punctuation character, the am is replaced by and redisplayed as abbrev mode. If we capitalize the abbreviation, Am, the expansion is capitalized: Abbrev mode. If we capitalize the whole abbreviation, AM, each word in the expansion is capitalized: Abbrev Mode. In this particular example, though, we would define am to expand to Abbrev Mode since it should always to be capitalized that way. With the am abbreviation defined like this, typing In am now would produce In Abbrev Mode now.
Abbreviation Mode does not interfere with the use of major modes, such as Text, Lisp or Pascal; nor does it interfere with other minor modes, such as Auto-fill. Each mode may redefine which functions are bound to characters; this does not affect Abbreviation Mode.
There are two scopes of abbreviation: local and global. A local abbreviation applies only in a buffer which is associated to the named local abbreviation table, while a global abbreviation applies in all buffers. If an abbreviation is defined both as a local abbreviation for the current buffer and as a global abbreviation, the local abbreviation expansion takes precedence over the global expansion.
Abbreviations can be defined one at a time (adding them as you think of them), or many at a time from an abbreviation file. You can save them in a file and read them back later. If you turn off Abbreviation Mode, abbreviations stop expanding automatically, but their definitions are remembered in case you turn Abbreviation Mode back on.
Start defining a keyboard macro. | ^X-( (start-remembering) |
End the definition of a keyboard macro. | ^X-) (stop-remembering) |
Execute the most recent keyboard macro. | ^X-e (execute-keyboard-macro) |
You can define a keyboard macro to abbreviate a sequence of other commands. If you discover that you are about to type ^U-^D forty times, you can define a keyboard macro to execute ^U-^D and call it with a repeat count of forty.
Keyboard macros differ from ordinary Emacs commands in that they are written as keystrokes rather than as MLisp code. This makes it easier for novices to use them.
You define a keyboard macro while executing the commands which are part of the definition. In this way, you can see what the effects of your commands are -- you do not have to work them out in your head. When you have finished, the keyboard macro is defined and has also been, in effect, executed once. You can execute the sequence of commands again by invoking the macro.
To start defining a keyboard macro, type the ^X-( command. From then on, your commands continue to be executed, but also become part of the macro definition. When you have finished, the ^X-) command terminates the definition (without becoming part of it!).
The newly-defined macro can then be invoked with the ^X-e command. You can give ^X-e a repeat count as a prefix argument to execute the several times.
There are two ways of using a keyboard macro to perform some action on each line in the buffer. The first is to start by positioning dot on the line above the first line to be processed, then begin the macro definition with a ^N (next-line). The second method is to start on the proper line, and end the macro with a ^N. Repeating the macro will operate on successive lines using either method.