Go to the previous, next section.
This chapter prematurely describes new features of Emacs 19, in anticipation of its release. We have included this so that the version 18 manuals don't become obsolete as soon as Emacs 19 comes out. This list mentions only features that would belong in The GNU Emacs Manual; changes relevant to Emacs Lisp programming will be documented in the next revision of The GNU Emacs Lisp Manual.
We have made changes to help Emacs use fewer resources and make it less likely to become irreparably hung. While these changes don't alter the commands of Emacs, they are important enough to be worth mentioning.
You can quit with C-g while Emacs is waiting to read or write a file--provided the operating system will allow you to interrupt the system call that is hung. (Unfortunately, most NFS implementations won't allow interruption.)
When you kill buffers, Emacs now returns memory to the operating system, thus reducing the size of the Emacs process. The space that you free up by killing buffers can now be reused for other buffers no matter what their sizes, or reused by other processes if Emacs doesn't need it.
When using X windows, you can now create more than one window at the X level. Each X window displays a frame which can contain one or several Emacs windows. Each frame has its own echo area and normally its own minibuffer. (To avoid confusion, we reserve the word "window" for the subdivisions that Emacs implements, and never use it to refer to a frame.) The easiest way to create additional frames is with the C-x 5 prefix character (see section New Everyday Commands).
Emacs windows can now have scroll bars; use the scroll-bar-mode
command to turn scroll bars on or off. 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. (You can control scroll
bars on a frame by frame basis by writing a Lisp program.)
Undoing a deletion now puts the cursor position where it was just before the deletion.
Emacs now does garbage collection and auto saving while it is waiting
for input, which often avoids the need to do these things while you are
typing. The variable auto-save-timeout says how many seconds
Emacs should wait, after you stop typing, before it does an auto save
and perhaps also a garbage collection. (The actual time period varies
also according to the size of the buffer--longer for longer buffers,
since auto saving itself is slower for long buffers.) This way, Emacs
does not interrupt or delay your typing.
In Emacs 18, when auto saving detects that a buffer has shrunk greatly, it refrains from auto saving that buffer and displays a warning. In version 19, it also turns off Auto Save mode in that buffer, so that you won't get the same warning repeatedly. If you reenable Auto Save mode in that buffer, Emacs will start saving it again despite the shrinkage.
In Emacs 19, revert-buffer no longer offers to revert from the
latest auto-save file. That option hasn't been very useful since the
change to keep more undo information.
The command recover-file no longer turns off Auto Save mode.
The user option for controlling whether files can set local variables is
called enable-local-variables in Emacs 19, rather than
inhibit-local-variables. A value of t means
local-variables lists are obeyed; nil means they are ignored;
anything else means query the user.
You can now get back recent minibuffer inputs conveniently. While in
the minibuffer, type M-p (previous-history-element) to fetch
the next earlier minibuffer input, and use M-n
(next-history-element) to fetch the next later input.
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 always use the minibuffer to
read their arguments even though you are already in the minibuffer when
you issue them.
We may have changed the precise way these commands work by the time you use Emacs 19. Perhaps they will search for a match for the string given so far in the minibuffer; perhaps they will search for a literal match rather than a regular expression match; perhaps they will only accept matches at the beginning of a history element; perhaps they will read the string to search for incrementally like C-s. We want to choose an interface that is convenient, flexible and natural, and these goals are somewhat contradictory. To find out what interface is actually available, type C-h f previous-matching-history-element.
The history feature is available for all uses of the minibuffer, but
there are separate history lists for different kinds of input. 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 also very specific history lists, such
as the one that compile uses for compilation commands.
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.
There is now a convenient way to enable flow control when your terminal or your connection won't work without it. Suppose you want to do this on VT-100 and H19 terminals; put the following in your `.emacs' file:
(evade-flow-control-on "vt100" "h19")
When flow control is enabled, you must type C-\ to get the effect of a C-s, and type C-^ to get the effect of a C-q.
The default setting of the Lisp variable version-control now
comes from the environment variable VERSION_CONTROL. Thus, you
can select a style of backup file naming for Emacs and other GNU
utilities all together.
backward-paragraph. The old key
sequence for this, M-[, is now undefined by default.
The reason for this change is to avoid conflict with the sequences that function keys send on most terminals.
forward-paragraph. The old key
sequence for this, M-], is now undefined by default.
We changed this to go along with M-{.
upcase-region) and C-x
C-l (downcase-region), are now disabled by default; these
keys seem to be often hit by accident, and can be quite
destructive if their effects are not noticed immediately.
split-window-horizontally,
which splits a window into two side-by-side windows. This used to be
C-x 5.
display-buffer, which displays a specified
buffer in another window without selecting it.
fill-region.
This command used to be run more often by mistake than on purpose.
add-mode-abbrev (previously C-x C-a).
add-global-abbrev (previously C-x +).
inverse-add-mode-abbrev (previously C-x C-h).
inverse-add-global-abbrev (previously C-x -).
expand-abbrev (previously C-x ').
narrow-to-region (previously C-x n).
narrow-to-page (previously C-x p).
widen (previously C-x w).
point-to-register (previously C-x /).
point-to-register (previously C-x /).
jump-to-register (previously C-x j).
copy-to-register (previously C-x x).
insert-register (previously C-x g).
copy-rectangle-to-register (previously C-x r).
kill-rectangle (no previous key binding).
yank-rectangle (no previous key binding).
open-rectangle (no previous key binding).
frame-configuration-to-register (a new command)
saves the state of all windows in all frames.
Use C-x r j to restore the configuration.
window-configuration-to-register (a new command)
saves the state of all windows in the selected frame.
Use C-x r j to restore the configuration.
The old key bindings C-x /, C-x j, C-x x and C-x
g have not yet been removed. The other old key bindings listed have
been removed. The old key binding C-x a, which was
append-to-buffer, was removed to make way for a prefix key; now
append-to-buffer has no keybinding.
zap-to-char) now kills through the target
character. In version 18, it killed up to but not including the target
character.
shell-command) now runs the specified
shell command asynchronously if it ends in `&', just as the shell
does.
split-window-vertically) now tries to
avoid scrolling by putting point in whichever window happens to contain
the screen line the cursor is already on. If you don't like this, you
can turn it off by setting split-window-keep-point to
nil.
save-some-buffers) now gives you more
options when it asks whether to save a particular buffer. The options
are analogous to those of query-replace. Here they are:
save-some-buffers without any more saving.
save-some-buffers without even asking
about other buffers.
save-some-buffers, which asks the
question again.
There is now a special major mode for editing `ChangeLog' files. It makes filling work conveniently. Each bunch of grouped entries is one paragraph, and each collection of entries from one person on one day is considered a page.
compare-windows ignores changes in
whitespace. If the variable compare-ignore-case is
non-nil, it ignores differences in case as well.
compile conveniently using the
minibuffer history commands, while in the minibuffer entering the
compilation command.
While a compilation is going on, the string `Compiling' appears in the mode line. When this string disappears, the compilation is finished.
The buffer of compiler messages is in Compilation mode. This mode provides the keys SPC and DEL to scroll by screenfuls, and M-n and M-p to move to the next or previous error message. You can also use M-{ and M-} to move up or down to an error message for a different source file. Use C-c C-c on any error message to find the corresponding source code.
Emacs 19 has a more general parser for compiler messages. For example, it can understand messages from lint, and from certain C compilers whose error message format is unusual.
iconify-frame) now
iconifies the current frame.
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.
isearch-backward-regexp,
which does reverse incremental regexp search.
find-file-other-frame and switch-to-buffer-other-frame.
mail-other-frame).
find-tag-other-frame).
find-file-read-only-other-window.
c-beginning-of-statement and c-end-of-statement).
c-fill-paragraph, which is designed
for filling C comments. (We assume you don't want to fill the actual C
code in a C program.)
c-up-conditional moves back to the containing
preprocessor conditional, setting the mark where point was previously.
A prefix argument acts as a repeat count. With a negative argument, this command moves forward to the end of the containing preprocessor conditional. When going backwards, `#elif' acts like `#else' followed by `#if'. When going forwards, `#elif' is ignored.
comment-region command adds comment delimiters to the lines
that start in the region, thus commenting them out. With a negative
argument, it deletes comment delimiters from the lines in the
region--this is the inverse of the effect of comment-region
without an argument.
With a positive argument, comment-region adds comment delimiters
but duplicates the last character of the comment start sequence as many
times as the argument specifies. This is a way of calling attention to
the comment. In Lisp, you should use an argument of at least two, because
the indentation convention for single semicolon comments does not leave
them at the beginning of a line.
apropos except that it searches for a
regular expression instead of merely a substring.
If you use a prefix argument (regardless of its value) with
apropos or super-apropos, they also search documentation
strings for matches as well as symbol names. The prefix argument also
controls looking up and printing the key bindings of all commands.
diff program come from the
variable diff-switches, whose value should be a string.
The buffer of differences has Compilation mode as its major mode, so you can use C-x ` to visit successive changed locations in the two source files, or you can move to a particular hunk of changes and type C-c C-c to move to the corresponding source. 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.
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 most important change in incremental search is that RET now terminates a search, and ESC does not. The other changes are useful, but not vital to know about.
To search for a newline in an incremental search, type LFD (also known as C-j).
(This change is somewhat of an experiment; it might be taken back by the time Emacs 19 is really released.)
fill-individual-paragraphs now has two modes. Its default mode
is that any change in indentation starts a new paragraph. The alternate
mode is that only separator lines separate paragraphs; this can handle
paragraphs with extra indentation on the first line. To select the
alternate mode, set fill-individual-varying-indent to a
non-nil value.
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.
Adaptive Fill mode doesn't have much effect on M-q in most major modes, because an indented line will probably count as a paragraph starter and thus each line of an indented paragraph will be considered a paragraph of its own.
c-fill-paragraph, which is designed
for filling C comments. (We assume you don't want to fill the actual C
code in a C program.)
The old TeX mode bindings of M-{ and M-} have been
moved to C-c { and C-c }. (These commands are
up-list and tex-insert-braces; they are the TeX
equivalents of M-( and M-).)
The new command C-c C-o (tex-latex-block) inserts a
matching `\begin'--`\end' pair. The new command C-c C-e
(tex-close-latex-block) inserts a matching `\end' for the
last unterminated `\begin'.
You can run BibTeX on the current file using C-c TAB
(tex-bibtex-file).
There is a new command C-c C-v (tex-view) for running a
DVI previewer.
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'.
There is now a third variant of TeX mode, for SliTeX. This is in addition to the variants for plain TeX and LaTeX. As before, the correct variant is chosen automatically when you visit a file.
Shell mode has been completely replaced with a new implementation. The basic idea is the same: Emacs runs a subshell, and all input and output to the subshell go through the shell buffer. But the special commands of Shell mode have been redesigned.
comint-dynamic-complete).
comint-dynamic-list-completions).
comint-previous-input) to
recall the last input; it copies the text of that input to the place
where you are editing. If you repeat M-p, it replaces the copied
input with successively earlier inputs. M-n is similar but goes in the
opposite direction, towards the present (comint-next-input).
When you find the previous input you want, you can resubmit it by typing RET, or you can edit it first and then resubmit it if you wish.
These shell history commands operate outside the minibuffer, but they are completely analogous to the minibuffer history commands.
comint-previous-matching-input) to
yank a previous input from the history which starts with that string.
You can repeat M-r to find successively earlier inputs starting
with the same string.
You can start moving in the opposite direction (toward more recent
inputs) by typing M-s (comint-next-matching-input) instead
of M-r. As long as you don't use any commands except M-r
and M-s, they keep using the same string that you had entered
initially.
These commands serve a purpose similar to that of M-r and M-s in the minibuffer, but do not work in quite the same way. We may change the interface of these commands, as well as that of the analogous minibuffer commands; one goal will be to make the two sets of commands compatible. But we haven't yet figured out which of the possible interfaces is best. To find out what interface is actually supported in Emacs 19, type C-h f comint-previous-matching-input RET.
comint-kill-output). This is useful if a shell command spews
out lots of output that just gets in the way.
comint-show-output).
Emacs 19 uses the Ispell program for spelling correction instead of the Unix spell program. Ispell has many advantages; one is that it can be started the first time you check a word, and left running thereafter, which makes further checking much faster. If you want to get rid of the Ispell process, use M-x kill-ispell.
To check the entire current buffer, use M-x ispell-buffer. Use M-x ispell-region to check just the current region.
Ispell commands often involve interactive replacement of words. You can interrupt the interactive replacement with C-g. You can restart it again afterward with C-u M-$.
Interactive replacement shows you one misspelling at a time and asks you what to do. To answer, type one of the following characters:
When the Ispell process starts, it reads your private dictionary which is the file `~/ispell.words'. Words that you "insert" with the i command are added to that file, but not right away--only at the end of the interactive replacement procedure.
Use the M-x reload-ispell command to reload your private dictionary from `~/ispell.words' if you edit the file outside of Ispell.
`%' is now a word-separator character in Mail mode. This is because that character frequently appears in addresses.
If you set the variable mail-signature non-nil, then
mail inserts the contents of your `.signature' file
automatically when it initializes a mail buffer. If you don't want your
signature in a particular message, just delete it from the buffer before
you send the message.
You can specify the text to insert at the beginning of each line when
you use C-c C-y to yank the message you are replying to. Set
mail-yank-prefix to the desired string. A value of nil
(the default) means to use indentation, as in Emacs 18. If you use
C-u by itself as the prefix argument to C-c C-y, then it
does not insert anything at the beginning of the lines, regardless of
the value of mail-yank-prefix.
You can easily convert an Rmail file to system mailbox format with the
command unrmail. This command reads two arguments, the name of
the Rmail file to convert, and the name of the new mailbox file.
The Rmail file is unchanged by this command.
Rmail now initially positions you at the first message in the Rmail file that you have not seen. This may not be a message that just arrived; it may have arrived in a previous session during which you did not select it. You can then read all the unseen messages going forwards.
When a message that you sent "bounces" back to you, you can retry
sending it by typing C-M-m (rmail-retry-failure) on the
failure message.
By contrast, the new command M-x rmail-resend is used for forwarding a message and marking it as "resentby" you, with the special header fields `Resent-by:' and `Resent-to:'.
Another new Rmail command is <, which moves to the first message. (This is for symmetry with >.) < is actually an alias for j.
e (rmail-edit-current-message) is now the command
to edit a message. To expunge, type x. We know
this will surprise people some of the time, but the surprise will not be
disastrous--if you type e meaning to expunge, just type C-c
C-c to leave Rmail Edit mode, and then type x.
The variable rmail-output-file-alist now controls the default
for the file to output a message to.
In the Rmail summary, C-n and C-p are now ordinary cursor motion commands. To move in the summary and select a new message, use n and p (which skip deleted messages) or M-n and M-p (which stop at all messages). These are, of course, the same commands you would use in the Rmail buffer.
M-. (find-tag) and the other commands to find a tag now
look first for an exact match in the tags table, and try substring
matches only afterward.
Another change in M-. is that it has no effect on what M-, will do subsequently. You can no longer use M-, to find the next similar tag; instead, use M-. with a prefix argument.
The new command find-tag-regexp successively visits the tags that
match a specified regular expression.
You can now use more than one tags table. Using visit-tags-table
to load a new tags table does not discard the other tables previously
loaded. The other tags commands use all the tags tables that are
loaded; the first one they use is the one that mentions the current
visited file.
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 find-tag 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.
You can now use the tags table for completion of names during ordinary editing. The command M-TAB (except in Emacs Lisp and Lisp Interaction modes) completes the identifier in the buffer before point, using the set of all tags as the list of possible completions.
tags-query-replace and tags-search now create buffers only
temporarily for the files that they have to search (those which are not
already visited in Emacs buffers). If one of these files contains a
match for the search pattern, then its buffer continues to exist;
otherwise, it is killed.
There are new commands in Info mode.
If you click the middle mouse button near a cross-reference, menu item or node pointer while in Info, you will go to the node which is referenced.
The variable Info-directory-list specifies a list of directory
names that contain Info files. Each time Info looks for an Info file,
it searches all these directories. This makes it easy to install the
Info files that come with various packages. You can specify the path
with the environment variable INFOPATH.
Dired has many new features which allow you to do these things:
There are now two kinds of marker that you can put on a file in Dired: `D' for deletion, and `*' for any other kind of operation. The x command deletes only files marked with `D', and most other Dired commands operate only on the files marked with `*'.
To mark files with `D' (also called flagging the files), you can use d as usual. Here are some commands for marking with `*' (and also for unmarking):
dired-mark).
dired-mark-executables).
With a prefix argument, unmark all those files.
dired-mark-symlinks). With a
prefix argument, unmark all those files.
dired-mark-directories). With a prefix argument,
unmark all those files.
dired-unmark-all-files).
With an argument, query for each marked file.
Type your help character, usually C-h, at that time for help.
To illustrate the power of this command, here is how to put `*' marks on all the files that were unmarked, while unmarking all those that had `*' marks:
c * t c SPC * c t SPC
The Dired commands to operate on files (rename them, copy them, and so on) have been generalized to work on multiple files. There are also some additional commands in this series.
All of these commands use the same convention to decide which files to manipulate:
Here are the commands that operate on multiple files in this way:
dired-do-copy). You must
specify a directory to copy into, or (if copying a single file) a new
name.
If dired-copy-preserve-time is non-nil, then copying with
this command sets the modification time of the new file to be the same
as that of the old file.
dired-do-rename). You must
specify a directory to rename into, or (if renaming a single file) a new
name.
Dired automatically changes the visited file name of buffers associated with renamed files so that they refer to the new names.
dired-do-hardlink).
You must specify a directory to make the links in, or (if making
just one link) the name to give the link.
dired-do-symlink).
You must specify a directory to make the links in, or (if making
just one link) the name to give the link.
dired-do-chmod). This calls the
chmod program, so you can describe the desired mode change with
any argument that chmod would handle.
dired-do-chgrp).
dired-do-chown).
(On most systems, only the superuser can do this.)
The variable dired-chown-program specifies the name of the
program to use to do the work (different systems put chown in
different places.
dired-do-compress).
dired-do-load).
dired-do-byte-compile).
dired-do-print). This command uses
the variables lpr-command and lpr-switches just as
lpr-file does (see section Hardcopy Output).
The dired command ! (dired-do-shell-command) reads a shell
command string in the minibuffer and runs the shell command on all the
specified files. There are two ways of applying a shell command to
multiple files:
Thus, ! tar cf foo.tar * RET runs tar on the entire
list of file names, putting them into one tar file `foo.tar'. The
file names are inserted in the order that they appear in the Dired
buffer.
For example, ! uudecode RET runs uudecode on each
file.
What if you want to run the shell command once for each file but with
the file name inserted in the middle? Or if you want to use the file
names in a more complicated fashion? Use a shell loop. For example,
this shell command would run uuencode on each of the specified
files, writing the output into a corresponding `.uu' file:
for file in *; uuencode $file $file >$file.uu; done
The working directory for the shell command is the top level directory of the Dired buffer.
The ! command does not attempt to update the Dired buffer to show new or modified files, because it doesn't know what those files might be. Type g to update the Dired buffer.
Here are commands that select files according to a regular expression:
dired-mark-files-regexp).
Only the non-directory part of the file name is used in matching. Use `^' and `$' to anchor matches. Exclude subdirs by hiding them (see section Hiding Subdirectories).
dired-flag-files-regexp).
The four regular expression substitution commands effectively perform
query-replace-regexp on the selected file names in the Dired
buffer. They read two arguments: a regular expression from, and a
substitution pattern to. Each selected file name is matched
against the regular expression, and then the part which matched is
replaced with the substitution pattern. You can use `\&' and
`\digit' in the substitution pattern to refer to all or part
of the old file name.
Thus, % R ^.*$ RET x-\& RET renames each selected file by prepending `x-' to its name. The inverse of this is to remove `x-' from the front of each file name. One way to do that is % R ^x-.*$ RET \& RET; another is % R ^x- RET RET. (Use `^' and `$' to anchor matches that should span the whole filename.)
If the regular expression matches more than once in a file name, only the first match is replaced.
Normally, the replacement process does not consider the directory names; it operates on the file name within the directory. If you specify a prefix argument of zero, then replacement affects the entire file name.
Often you will want to apply the command to all files matching the same regexp that you use in the command. To do this, mark those files with % m regexp RET, then use the same regular expression in % R. To make this easier, % R uses the last regular expression specified in a % command as a default.
Here are commands for changing the case of selected files:
% u
dired-upcase).
% l
dired-downcase).
Here are two commands to run diff on selected files:
diff program (dired-diff). The file at the
mark is the first argument of diff, and the file at point is the
second argument.
dired-backup-diff).
If there are several numerical backups, use the most
recent one. If this file is a backup, compare it to its
original. The backup file is the first file given to diff.
One Dired buffer can now display more than one directory.
The simplest way to include multiple directories is to specify the
options `-lR' for running ls. That produces a recursive
directory listing showing all subdirectories, all within the same Dired
buffer.
But the simplest way is not usually the most convenient way--usually the complete recursive listing is more than you want. So there is a Dired command to insert a single subdirectory into the Dired buffer:
dired-maybe-insert-subdir) command on a line
that describes a file which is a directory. It inserts the contents of
that directory into the same Dired buffer. Inserted subdirectory
contents follow the top-level directory of the Dired buffer, just as
they do in `ls -lR' output.
If the subdirectory's contents are already present in the buffer, the
i command just moves to it (type l
(dired-do-redisplay) to refresh it). It sets the Emacs mark
before moving, so C-x C-x takes you back to the old position in
the buffer.
When you have subdirectories in the Dired buffer, you can use the page motion commands C-x [ and C-x ] to move by entire directories.
The following commands move up and down in the tree of directories in one Dired buffer:
dired-tree-up).
dired-tree-down).
The following commands move forwards and backwards to subdirectory headerlines:
dired-next-subdir).
dired-prev-subdir).
Hiding a subdirectory means to make it invisible, except for its headerline. Files inside a hidden subdirectory are never considered by Dired. For example, the commands to operate on marked files ignore files in hidden directories even if they are marked. Thus you can use hiding to temporarily exclude subdirectories from operations without having to remove the markers.
The hiding commands toggle; that is they unhide what was hidden and vice versa.
dired-hide-subdir). A prefix argument serves as
a repeat count.
dired-hide-all). Or, if any subdirectory is currently hidden,
make all subdirectories visible again. You can use this command to get
an overview in very deep directory trees or to move quickly to
subdirectories far away.
dired-do-redisplay).
If you use this command on a subdirectory header line, it updates the contents of the subdirectory.
revert-buffer). Preserve all marks except for those on files
that have vanished. Hidden subdirectories are updated but remain
hidden.
dired-do-kill-lines). With a prefix
argument, kill that many lines starting with the current line.
This command does not delete files; it just deletes text from the Dired buffer.
If you kill the line for a file that is a directory, then its contents are also deleted from the buffer. Typing C-u k on the header line for a subdirectory is another way to delete a subdirectory from the Dired buffer.
The g command will bring back any individual lines that you have killed in this way, but not subdirectories--you must use i to reinsert each subdirectory.
find
You can select a set of files for display in a Dired buffer more
flexibly by using the find utility to choose the files.
To search for files with names matching a wildcard pattern use
find-name-dired. Its arguments are directory and
pattern. It selects all the files in directory or its
subdirectories whose own names match pattern.
The files thus selected are displayed in a Dired buffer in which the ordinary Dired commands are available.
If you want to test the contents of files, rather than their names, use
find-grep-dired. This command takes two minibuffer arguments,
directory and regexp; it selects all the files in
directory or its subdirectories that contain a match for
regexp. It works by running find and grep.
The most general command in this series is find-dired, which lets
you specify any condition that find can test. It takes two
minibuffer arguments, directory and find-args; it runs
find in directory with find-args as the
arguments to find that specify which files to accept. To use this
command, you need to know how to use find.
GNUS is an Emacs subsystem for reading and responding to netnews. You can use GNUS to browse through news groups, look at summaries of articles in specific group, and read articles of interest. You can respond to authors or write replies to all the readers of a news group.
This document introduces GNUS and describes several basic features. Full documentation will appear in The GNU Emacs Extensions Manual.
To start GNUS, type M-x gnus RET.
GNUS creates and uses three Emacs buffers, each with its own particular purpose and its own major mode.
The Newsgroup buffer contains a list of newsgroups. This is the first buffer that GNUS displays when it starts up. Normally the list contains only the newsgroups to which you subscribe (which are listed in your `.newsrc' file) and which contain unread articles. Use this buffer to select a specific newsgroup.
The Summary buffer lists the articles in a single newsgroup, including their subjects, their numbers, and who posted them. GNUS creates a Summary buffer for a newsgroup when you select the group in the Newsgroup buffer. Use this buffer to select an article, and to move around in an article.
The Article buffer displays the text of an article. You rarely need to select this buffer because you can read the text while keeping the Summary buffer selected.
At startup, GNUS reads your `.newsrc' news initialization file and attempts to communicate with the local news server, which is a repository of news articles. The news server need not be the same computer you are logged in on.
If you start GNUS and connect to the server, but do not see any newsgroups listed in the Newsgroup buffer, type L to get a listing of all the newsgroups. Then type u to unsubscribe from particular newsgroups. (Move the cursor using n and p or the usual Emacs commands.) When you quit with q, GNUS automatically records the subscribed groups in your `.newsrc' initialization file. (You do not have to edit this file yourself, although you may.) Next time you start GNUS, you will see only the subscribed groups.
Reading news is a two step process:
Each buffer has commands particular to it, but commands that do the same things have similar keybindings. Here are commands for the Newsgroup and Summary buffers:
In the Summary buffer, exit the current newsgroup and return to the Newsgroup buffer. Thus, typing q twice quits GNUS.
You may also edit your `.newsrc' file directly in Emacs. First quit GNUS, then visit the `.newsrc' file. For example, you can remove all the `alt.' groups by going to the beginning of the file and typing M-x flush-lines RET alt RET. Next time you start GNUS, you will see only the newsgroups still listed in the `.newsrc' file.
In the Summary buffer,
Thus, you can move through all the articles by repeatedly typing SPC.
In the Summary buffer, scroll the text of the article backwards.
The calendar facility in Emacs 19 is almost completely new, and it comes with a diary feature. You can use the diary to keep track of appointments, anniversaries, and other events.
To use the diary, you must write diary entries in a particular file, called your diary file. Its name is `~/diary'. Emacs displays the entries for particular dates by finding them in the diary file, formatting them, and displaying them in a diary display buffer.
In Emacs 19 you can use ordinary Emacs cursor commands to move through the calendar, which scrolls automatically to display different months or different years. Character motion translates to days, line motion to weeks, sentence and paragraph motion to months, and page motion to years. The vertical and horizontal scroll commands also handle the calendar suitably.
p d displays the selected date as a day within the year. g d selects a date given as month, day, year. Type . to go back to today's date.
The command M-=, which normally gives the number of lines in the
region, in Calendar mode gives the number of days in the region
(calendar-count-days-region).
The calendar facility also knows about other important calendars. The commands for these come in pairs; the commands to convert to another calendar start with the p prefix (short for "print"), and the commands to convert from another calendar start with the g prefix (short for "go to"). Here is a complete list:
calendar-goto-astro-date, calendar-print-astro-date).
calendar-goto-iso-date, calendar-print-iso-date).
calendar-goto-french-date,calendar-print-french-date).
calendar-goto-hebrew-date,calendar-print-hebrew-date).
calendar-goto-islamic-date,calendar-print-islamic-date).
calendar-goto-julian-date,calendar-print-julian-date).
calendar-print-mayan-date).
The calendar also knows the dates of standard holidays. Type h
(calendar-cursor-holidays) to display a list of holidays for the
selected date. This list appears in another window. Type x
(mark-calendar-holidays) to mark each day that is a holiday with
`*' in the calendar itself. The command u
(calendar-unmark) turns off this marking.
At any time, you can use M-x holidays to display a list of holidays for the present month and the preceding and following months.
To use the diary feature, you must write diary entries that
describe plans associated with particular dates, and put them in your
diary file, which is normally the file `~/diary'. You can
specify a different name for it by setting the variable
diary-file; you would do this before using any of the commands
that operate on the diary.
Diary file entries follow a simple convention: begin entries with a date at the beginning of a line, followed optionally by a time, and then by the text of the entry:
date optional-time-of-day text-of-entry
To continue an entry over two or more lines, indent the second and subsequent lines. The lines of the entry after the first are called continuation lines. Other lines in the diary file that are not part of any entry are comment lines; Emacs does not display these.
When you make diary entries using Calendar mode, Emacs inserts the date for you in the appropriate format and places the cursor so you can type the text of the entry.
You can write entries in any order and Emacs will display the entries by date. However, time-of-day entries can be sorted chronologically only in a diary mode called Fancy mode; in Simple mode, Emacs displays time-of-day entries in their order in the diary file.
In Calendar mode, use the following commands to display your diary entries:
view-diary-entries).
With a numeric argument, Emacs shows the diary entries for that many successive days, starting with and including the date under the cursor. Thus, 2 d displays all the entries for the selected date and for the following day.
show-all-diary-entries).
mark-diary-entries).
calendar-unmark).
At any time, not just in Calendar mode, you can display today's diary entries by typing:
M-x diary
With a prefix argument n, this command displays diary entries for n successive days, starting from and including today.
Calendar mode provides several commands to help you make diary file entries. These commands work by visiting the diary file and inserting the date information; you must finish the job by inserting the text of the entry, and then save the diary file with C-x C-s. The commands are:
insert-diary-entry).
insert-weekly-diary-entry). This entry is displayed each week
on the selected day.
insert-monthly-diary-entry). This entry is displayed each month
on the selected day.
insert-yearly-diary-entry). This entry is displayed each year
on the selected day.
Here are commands for entering more complex kinds of diary entries in Calendar mode. These kinds of entries operate properly only in Fancy Diary Display mode (see section Simple and Fancy Diary Display).
insert-anniversary-diary-entry).
Select the date you want remembered, in the proper year--if it is a birthday, remember to go to the person's year of birth! Then type i a and enter the text of the entry.
In the textual part of the entry you can type `%d'. When Emacs displays the entry in the diary buffer, the `%d' is replaced by the number of years since the date. Thus, if you use `%d years old' as the text of the entry, it will display as `53 years old' on the 53rd birthday.
insert-cyclic-diary-entry). An entry is displayed on a
specified starting date and then is repeatedly displayed at the
specified interval. This is useful for ten day cycles of preventive
maintenance and similar activities.
To use this command, first select the start date. The command reads the interval (the number of days between repetitions) using the minibuffer, then inserts the beginning of the entry.
insert-block-diary-entry). With a block entry, Emacs
writes the same message in the display for successive days.
Position point and mark at the beginning and end of the block of days you want entered and type i b. This sets up the diary entry's date info and positions point so you can write the text of the entry. People usually use this command for trips or vacations.
By default, Emacs interprets and displays diary dates in civilian American form, `month/day/year': `2/15/1993', or `February 15, 1993'.
Alternatively, you can specify the European calendar style for writing
dates: `day/month/year', `15/2/1993' or
`15 February 1993'. To do this, set the variable
european-calendar-style to t, before using any calendar or
diary command. This also affects display of dates.
Here's how to do this in your `.emacs' file:
(setq european-calendar-style t)
There are two modes for displaying a subset of diary entries: Simple mode and Fancy mode. Fancy mode provides a more dramatic display for the diary, and can also display the actual matching date for diary entries that match more than one date.
By default, Emacs uses Simple mode, which is quicker than Fancy mode.
Another advantage of Simple mode is that you can edit the displayed
diary entries "in place" and save them. When you use Fancy mode, it
is useless to edit the displayed subset of the diary; instead you must
visit the diary file separately. To select Fancy mode, set
diary-display-hook to fancy-diary-display like this:
(setq diary-display-hook 'fancy-diary-display)
Here are some additional diary features. These will be explained in full in The GNU Emacs Extensions Manual.
You can schedule meetings on a date such as the first Tuesday of every month. This is called an offset date. The diary has commands for specifying such meetings, but not in Calendar mode. To create such an entry, you need to edit the diary file yourself.
You can make entries according to Hebrew and Islamic dates. Calendar
mode provides commands of the form i h d to add a diary entry
for the Hebrew date corresponding to the selected date and i i d
to add a diary entry for the Islamic date corresponding to the selected
date. You can make entries that repeat every week, month, or year.
Before using these commands, you must set the
nongregorian-diary-listing-hook and the
nongregorian-diary-marking-hook in your `.emacs' file.
You can include other diary files in your diary display. This way, a group of people can share a common diary file.
If you start a new Emacs each day, you might want to display your diary automatically at that time. To do so, put this in your `.emacs' file:
(diary)
If you want to see both the calendar and your diary at startup, use this instead:
(setq view-diary-entries-initially t) (calendar)
To print the selected diary entries as they appear on the screen, use
M-x print-diary-entries. The same variables that customize
lpr-buffer also affect this command.
In Simple mode, the diary display buffer uses selective display
(see section Selective Display). This means that what you see on the screen
is just part of the text in the Emacs buffer. The diary entries that
don't apply to the dates you asked for are still in the buffer, but
hidden. The ordinary printing commands such as lpr-buffer would
not do what you want; they print the entire text, including the hidden
parts. This is why we need print-diary-entries.
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 change comment for each 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 file (typically, the most recent) from the master. 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. 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.
These are the basic operations of version control.
Checking in and checking out both use the single Emacs command
C-x C-q (vc-toggle-read-only).
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 `%%'.)
These are the commands that you use to edit 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.)
If you want to edit the file, type C-x C-q
(vc-toggle-read-only). This checks out and locks the file,
so that you can edit it. The file is writable after check-out, but only
for you, not for anyone else.
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-backups to a non-nil value.
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 a 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.
Once you have checked in your changes, the file is unlocked, so that other users can lock it and modify it.
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.
Actually, 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 or her of what has happened.
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 requies 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 if you lock a file and then don't actually change it.
You can even cancel a change after checking it in, with C-x v c
(vc-cancel-version). Normally, C-x v c reverts your
workfile and buffer to the previous version (the one that precedes the
version that is deleted), but you can prevent the reversion by giving
the command a prefix argument. Then the buffer does not change.
This command with a prefix argument is useful when you have checked in a change and then discover a trivial error in it; you can cancel the erroneous check-in, fix the error, and repeat the check-in.
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 asks for confirmation with `yes'.
You can register the visited file for version control using
C-x v i (vc-register). This uses RCS if RCS
is installed on your system; otherwise, it uses SCCS.
By default, the initial version number is 1.1. If you want to use a different number, give C-x v i a prefix argument; then it reads the initial version number using the minibuffer.
After C-x v i, the file is unlocked and read-only. Type C-x C-q if you wish to edit it.
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, then you can set vc-mistrust-permissions to t
so that VC always checks the master file.
When you're editing an initial or change comment 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 comment 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 they don't use the minibuffer).
The history of previous log entries is actually stored in previous pages of the log entry editing buffer; they are normally hidden by narrowing.
Each time you check in a file, the log entry buffer is put into VC Log
mode, which involves running two hook variables: text-mode-hook
and vc-log-mode-hook.
Emacs users often record brief summaries of program changes in a file called `ChangeLog', which is kept in the same directory as the source files, and is usually meant to be distributed along with the source files. You can maintain `ChangeLog' from the version control logs with the following command.
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 suppose 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:
Fri May 8 21:45:00 1992 Nathaniel Bowditch (nat@apn.org)
* rcs2log: Ignore log messages that start with `#'.
You can then further edit as you wish.
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'.
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 check-ins 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':
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.
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:
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.
Normally, the log entry for file `foo' is displayed as `* foo: text of log entry'. But by convention, 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:
Wed May 6 10:53:00 1992 Nathaniel Bowditch (nat@apn.org)
* vc.el (vc-do-command): Check call-process status.
To compare two versions of a file, use 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. With a prefix argument, C-x v = reads a filename and two version numbers, and compares those versions of the file you specify.
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; you can specify the most recent checked-in version with `-'; and you can specify the current buffer contents with `+'. Thus, you can compare two checked-in versions, or compare a checked-in version with the text you are editing.
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.
To get the detailed version control status of one 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 do so using these commands, both of which operate on the branch of the file system starting at the current directory.
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.
With a prefix argument, C-x v d shows all the version control activity in the current directory--it lists all files in or beneath the current directory that are maintained with version control.
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.
vc-rename-file is not bound to a key because it's not likely
to be used frequently.
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 function 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.
You shouldn't need to use vc-retrieve-snapshot very often; you
can get difference reports between two snapshots without retrieving
either one, using C-x = (see section Comparing Versions). Thus,
retrieving a snapshot is only necessary if you need to study or compile
portions of the snapshot.
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 = (see section Comparing 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.
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 function 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). This 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.
If you use snapshots, don't rename either work files or master files
except by means of vc-rename-file. It knows how to update
snapshots so that you can still retrieve them. 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 teach the reader how to
update the snapshots by hand.
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 `$ld$' for RCS and `%W%' for
SCCS. You can specify other headers to insert by setting the variable
vc-header-string. Its value (if non-nil) should be the
string to be inserted. You can also 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 important to use "superfluous" backslashes when
writing a Lisp string constant for this use, 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).
vc-static-header-alist is consulted to add further strings based
on the name of the buffer. Its value should be a list of
dotted pairs; the CAR of each pair is a regular expression that
should match the buffer name, and the CDR is the format to use on
each header. A string is inserted for each file name pattern that
matches the buffer name, and for each header taken from
vc-header-string. The default value for
vc-static-header-alist is:
(("\\.c$" .
"\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\
#endif /* lint */\n"))
which specifies insertion of a string of this form:
#ifndef lint static char vcid[] = "header-string"; #endif /* lint */
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, you need to merge the two versions. Emerge makes this easier.
To start Emerge, run one of these four commands:
The Emerge commands compare two texts, and display the results in three buffers: one for each input text (the A buffer and the B buffer), and one (the merge buffer) where merging takes place. The merge buffer does not show just the differences. Rather, it shows you the full text, but wherever the input texts differ, you can choose which one of them to include in the merge buffer.
If a common ancestor version is available, from which the two texts to be merged were both derived, Emerge can use it to guess which alternative is right. Wherever one current version agrees with the ancestor, Emerge presumes that the other current version is a deliberate change which should be kept in the merged version. Use the "with-ancestor" commands if you want to specify a common ancestor text. These commands read three file or buffer names--variant A, variant B, and the common ancestor.
After the comparison is done and the buffers are prepared, the actual merging starts. You control the merging interactively by editing the merge buffer. The merge buffer shows you a full merged text, not just differences. For each point where the input texts differ, you can choose which one of them to include in the merge buffer.
The merge buffer has a special major mode, Emerge mode, with commands for making these choices. But you can also edit the buffer with ordinary Emacs commands.
At any given time, the attention of Emerge is focused on one particular difference, called the selected difference. This difference is marked off in the three buffers by
vvvvvvvvvvvvvvvvvvvv
above and
^^^^^^^^^^^^^^^^^^^^
below. Emerge numbers all the differences sequentially and the mode line always shows the number of the selected difference.
Normally, the merge buffer starts out with the A version of the text. But when the A version of a part of the buffer agrees with the common ancestor, then the B version is preferred for that part.
Normally, Emerge stores the merged output in place of the first input
text (the A file or buffer). If you give a prefix argument to
emerge-files or emerge-files-with-ancestor, it reads the
name of the output file using the minibuffer. (This is the last file
name those commands read.)
If you abort Emerge with C-u q, the output is not saved.
You can choose between two modes for giving merge commands: Fast mode and Edit mode. In Fast mode, basic Emerge commands are single characters, but ordinary Emacs commands are disabled. This is convenient if you use only Emerge commands.
In Edit mode, all Emerge commands start with the prefix character C-c, and the normal Emacs commands are also available. This allows editing the merge buffer, but slows down Emerge operations.
Use e to switch to Edit mode, and f to switch to Fast mode. The mode line indicates Edit and Fast modes with `E' and `F'.
Emerge has two additional submodes that affect how particular merge commands work: Auto Advance mode and Skip Prefers mode.
If Auto Advance mode is in effect, the a and b commands advance to the next difference. This lets you go through the merge faster doing ordinary things. The mode line indicates Auto Advance mode with `A'.
If Skip Prefers mode is in effect, the n and p commands skip over differences in states prefer-A and prefer-B. Thus you will only see differences for which neither version is presumed "correct". The mode line indicates Skip Prefers mode with `S'.
Use the command emerge-auto-advance-mode to set or clear Auto
Advance mode. Use emerge-skip-prefers-mode to set or clear Skip
Prefers mode. A positive argument turns the mode on, a nonpositive
argument turns it off, and no argument toggles it.
In the merge buffer, a difference is marked `vvvvvvvvvvvvvvvvvvvv' above and `^^^^^^^^^^^^^^^^^^^^' below. Such a difference can have one of seven states:
When you select a difference, its state changes from default-A or default-B to plain A or B. Thus, the selected difference never has state default-A or default-B, and these states are never displayed in the mode line.
The command d a chooses default-A as the default state, and d b chooses default-B. This chosen default applies to all differences which you haven't selected and for which no alternative is preferred. If you are moving through the merge sequentially, the differences you haven't selected are those following the selected one. Thus, while moving sequentially, you can effectively make the A version the default for some sections of the merge buffer and the B version the default for others by using d a and d b at the end of each section.
These two states are displayed in the mode line as `A*' and `B*'.
Once a difference is in this state, the a and b commands don't do anything to it unless you give them a prefix argument.
The mode line displays this state as `comb'.
Here are the Merge commands for Fast mode; in Edit mode, precede these with C-c and turn all the letters into control characters.
The q (emerge-quit) command finishes the merge, storing the
results into the output file. It restores the A and B buffers to their
proper contents, or kills them if they were created by Emerge. It also
disables the Emerge commands in the merge buffer, since executing them
later could damage the contents of the various buffers.
C-u q aborts the merge. Aborting means that Emerge does not write the output file.
If Emerge was called from another Lisp program, then its return value
is t or nil to indicate success or failure.
Sometimes you want to keep both alternatives for a particular locus. To do this, use x c, which edits the merge buffer like this:
#ifdef NEW version from A file #else /* NEW */ version from B file #endif /* NEW */
While this example shows C preprocessor conditionals delimiting the two
alternative versions, you can specify the strings you want by setting
the variable emerge-combine-template to a list of three strings.
The default setting, which produces the results shown above, looks like this:
("#ifdef NEW\n"
"#else /* NEW */\n"
"#endif /* NEW */\n")
You can have any number of merges going at once--just don't use any one buffer as input to more than one merge at once, since that will cause the read-only/modified/auto-save status save-and-restore to screw up.
Starting Emerge can take a long time because it needs to compare the
files. Emacs can't do anything else until diff finishes. Perhaps in
the future someone will change Emerge to do the comparison in the
background when the input files are large--then you could keep on doing
other things with Emacs until Emerge gets ready to accept commands.
After the merge has been set up, Emerge runs the hooks in
emerge-startup-hook.
During the merge, you musn't try to edit the A and B buffers yourself. Emerge modifies them temporarily, but ultimately puts them back the way they were.
The GUD (Grand Unified Debugger) library provides an interface to various symbolic debuggers from within Emacs. We recommend the debugger GDB, which is free software, but you can also run DBX or SDB if you have them.
There are three commands for starting a debugger. Each corresponds to a particular debugger program.
You can only run one debugger process at a time.
When you run a debugger with GUD, the debugger displays source files via Emacs--Emacs finds the source file and moves point to the line where the program is executing. An arrow (`=>') indicates the current execution line, and it stays put even if you move the cursor.
You can start editing the file at any time. The arrow is not part of the file's text; it appears only on the screen. If you do modify a source file, keep in mind that inserting or deleting lines will throw off the arrow's positioning; GUD has no way of figuring out which line corresponded before your changes to the line number in a debugger message. Also, you'll typically have to recompile and restart the program for your changes to be reflected in the debugger's tables.
If you wish, you can control your debugger process entirely through the debugger buffer, which uses a variant of Shell mode. All the usual commands for your debugger are available, and you can use the Shell mode history commands to repeat them.
GUD provides a command available in all buffers for setting breakpoints. This command is defined globally because you need to use it in the source files' buffers.
The debugger buffer has a number of keybindings for invoking common debugging commands quickly:
gud-refresh.
gud-step). If the code contains
a function call, execution stops after entering the called function.
gud-next).
gud-stepi).
gud-cont).
The above commands are common to all supported debuggers. If you are using GDB or (some versions of) DBX, these additional commands are available:
gud-up). This is
equivalent to the `up' command.
gud-down). This is
equivalent to the `down' command.
If you are using GDB, two additional keybindings are available:
These commands interpret a prefix argument as a repeat count, when that makes sense.
After each command that changes the program counter, GUD displays the new current source line, and updates the location of the arrow.
On startup, GUD executes one of the following hooks:
gdb-mode-hook, if you are using GDB; dbx-mode-hook, if you
are using DBX; and sdb-mode-hook, if you are using SDB. You can
use these hooks to define custom keybindings for the debugger
interaction buffer.
Here is a convenient way to define a command that sends a particular command string to the debugger, and set up a key binding for it in the debugger interaction buffer:
(gud-def function cmdstring binding docstring)
This defines a command named function which sends
cmdstring to the debugger process, with documentation string
docstring, and binds it to binding in the debugger buffer's
mode. (If binding is nil, this defines the command but
does not make a binding for it; you can make a binding explicitly,
perhaps using one of the above hooks.)
Commands defined with gud-def handle prefix arguments by
passing them to the debugger, appended to end of cmdstring with a
space in between. (This use of prefix arguments works with GDB and DBX,
but not with SDB.)
You can also set up commands that you can send to the debugger while in
another buffer, such as a source file. Set the variable
gud-commands to a list of strings containing debugger commands
you might want to send.
send-gud-command). Normally, send the CAR of the
gud-commands list; a prefix argument specifies which element of
that list to use (counting from 0).
If the string contains `%s', C-x & substitutes a numeric value found in the buffer at or near point. It looks for decimal, octal, or hexadecimal numbers, with `0x' allowed. This lets you define commands to chase pointers whose numeric values have been displayed.
There is now a Perl mode for editing Perl programs and an Icon mode for editing Icon programs.
C++ mode is like C mode, except that it understands C++ comment syntax
and certain other differences between C and C++. It also has a command
fill-c++-comment which fills a paragraph made of comment lines.
The command comment-region is useful in C++ mode for commenting
out several consecutive lines, or removing the commenting out of such
lines.
WordStar emulation is available--type M-x wordstar-mode. For more information, type C-h f wordstar-mode RET.
The command C-o in Buffer Menu mode now displays the current line's buffer in another window but does not select it. This is like the existing command o which selects the current line's buffer in another window.
Asm mode is a new major mode for editing files of assembler code. It defines these commands:
tab-to-tab-stop.
tab-to-tab-stop.
tab-to-tab-stop.
Edebug is a new source-level debugger for Emacs Lisp programs.
To use Edebug, use the command M-x edebug-defun to "evaluate" a function definition in an Emacs Lisp file. We put "evaluate" in quotation marks because it doesn't just evaluate the function, it also inserts additional information to support source-level debugging.
You must also do this:
(setq debugger 'edebug-debug)
to cause errors and single-stepping to use Edebug instead of the usual Emacs Lisp debugger.
For more information, see The Emacs Extensions Manual, which should be included in the Emacs 19 distribution.
There is a new major mode for editing binary files: Hexl mode. To use it, use M-x hexl-find-file instead of C-x C-f to visit the file. This command converts the file's contents to hexadecimal and lets you edit the translation. When you save the file, it is converted automatically back to binary.
You can also use M-x hexl-mode to translate an existing buffer into hex. This is useful if you visit a file normally and discover it is a binary file.
Hexl mode has a few other commands:
hexl-mode.
In Emacs 18, a key sequence was a sequence of characters, which represented keyboard input.
In Emacs 19, you can still use a sequence of characters as a key sequence, but you aren't limited to characters. You can also use Lisp symbols which represent terminal function keys or mouse buttons. If the function key has a word as its label, then that word is also the name of the symbol which represents the function key. Other function keys are assigned Lisp names as follows:
kp-add, kp-decimal, kp-divide, ...
kp-0, kp-1, ...
kp-f1, kp-f2, kp-f3, kp-f4
left, up, right, down
A key sequence which contains non-characters must be a vector rather than a string.
Thus, to bind function key `f1' to rmail, write the
following:
(global-set-key [f1] 'rmail)
(To find the name of a key, type C-h k and then the key.)
To bind the right-arrow key to the command forward-char,
you can use this expression:
(global-set-key [right] 'forward-char)
using the Lisp syntax for a vector containing the symbol right.
And this is how to make C-x RIGHTARROW move forward a page:
(global-set-key [?\C-x right] 'forward-page)
where ?\C-x is the Lisp syntax for an integer whose value is the
code for the character C-x.
You can use modifier keys such as CTRL, META and SHIFT with function keys. To represent these modifiers, prepend the strings `C-', `M-' and `S-' to the symbol name. Thus, here is how to make M-RIGHTARROW move forward a word:
(global-set-key [M-right] 'forward-word)
Emacs uses symbols to designate mouse buttons, too.
The ordinary mouse events in Emacs are click events; these
happen when you press a button and release it without moving the mouse.
You can also get drag events, when you move the mouse while
holding the button down. Drag events happen when you finally let go
of the button.
The symbols for basic click events are mouse-1 for the leftmost
button, mouse-2 for the next, and so on. Here is how you can
redefine the second mouse button to split the current window:
(global-set-key [mouse-2] 'split-window-vertically)
The symbols for drag events are similar, but have the prefix `drag-'
before the word `mouse'. For example, dragging the left button
generates a drag-mouse-1 event.
You can also request events when the mouse button is pressed down. These events start with `down-' instead of `drag-'. Such events are generated only if they have key bindings. When you get a button-down event, a corresponding click or drag event will always follow.
The symbols for mouse events also indicate the status of the modifier keys, with the usual prefixes `C-', `M-' and `S-'. These always follow `drag-' or `down-'.
When mouse events occur in special parts of a frame or window, such as a
mode line or a scroll bar, the event symbol shows nothing special. The
information about the special part is implicit in other data (the screen
location of the event). But read-key-sequence figures out this
aspect of the event, and encodes it with make-believe prefix keys, all
of which are symbols: mode-line, vertical-line,
horizontal-scrollbar and vertical-scrollbar. Thus, to
define the command for clicking the left button in a mode line, you
could use this key sequence:
[mode-line mouse-1]
You are not limited to defining individual function keys or mouse buttons; these can appear anywhere in a key sequence, just as characters can. You can even mix together all three kinds of inputs in one key sequence--but mixing mouse buttons with keyboard inputs is probably not convenient for actual use.
A hook variable is a variable that exists so that you can store in it functions for Emacs to call on certain occasions. (The functions that you put in hook variables are called hook functions.) Emacs 19 has a new convention for naming hook variables that indicates more reliably how to use them.
All the variables whose names end in `-hook' are normal
hooks; their values are lists of functions to be called with no
arguments. You can use add-hook (see below) to install hook
functions in these hooks. We have made all Emacs hooks into normal
hooks except when there is some reason this won't work.
A few hook-like variables are abnormal---they don't use the normal convention. This is either because the user-supplied functions receive arguments, or because their return values matter. These variables have names that end in `-function' (if the value is a single function) or `-functions' (if the value is a list of functions).
Thus, you can always tell from the variable's name precisely how to install a new hook function in the variable. If the name indicates a normal hook, then you also know how to write your hook function.
To add a hook function to a normal hook, use add-hook. It takes
care of adding a new hook function to any functions already installed in
a given hook. It takes two arguments, the hook symbol and the function
to add. For example,
(add-hook 'text-mode-hook 'my-text-hook-function)
is how to arrange to call my-text-hook-function when entering
Text mode or related modes.
Two new hooks are worth noting here. Expansion of an abbrev
first runs the hook pre-abbrev-expand-hook.
kill-buffer-hook now runs whenever a buffer is killed.
Go to the previous, next section.