Commit 6b8bc570 authored by Chong Yidong's avatar Chong Yidong

Merge changes from emacs-23 branch

parents 3726838a 0080dc6b
2011-03-26 Chong Yidong <cyd@stupidchicken.com>
* display.texi (Auto Scrolling): Fix scroll-up/scroll-down confusion.
2011-03-30 Eli Zaretskii <eliz@gnu.org>
* display.texi (Auto Scrolling): Document the limit of 100 lines
......
......@@ -206,16 +206,18 @@ how aggressively it scrolls by setting the variables
@code{scroll-up-aggressively} and @code{scroll-down-aggressively}.
The value of @code{scroll-up-aggressively} should be either
@code{nil}, or a fraction @var{f} between 0 and 1. A fraction
specifies where on the screen to put point when scrolling upward: when
a window scrolls up because point is above the window start, the new
specifies where on the screen to put point when scrolling upward,
i.e.@: when point moves forward in the buffer, and therefore text
scrolls up in the window. When point goes off the window end, the new
start position is chosen to put point @var{f} parts of the window
height from the top. Thus, larger @var{f} means more aggressive
scrolling. The default value, @code{nil}, is equivalent to 0.5.
height from the bottom. Thus, larger @var{f} means more aggressive
scrolling: more new text is brought into view. The default value,
@code{nil}, is equivalent to 0.5.
Likewise, @code{scroll-down-aggressively} is used for scrolling
down. The value specifies how far point should be placed from the
bottom of the window; thus, as with @code{scroll-up-aggressively}, a
larger value is more aggressive.
down, i.e.@: moving point back in the buffer. The value specifies how
far point should be placed from the top of the window; thus, as with
@code{scroll-up-aggressively}, a larger value is more aggressive.
These two variables are ignored if either @code{scroll-step} or
@code{scroll-conservatively} are set to a non-zero value.
......
2011-03-21 Stefan Monnier <monnier@iro.umontreal.ca>
* minibuf.texi (Basic Completion): Be a bit more precise about the
valid kinds of completion tables.
(Programmed Completion): Remove obsolete text about lambda expressions
not being valid completion tables.
2011-03-19 Chong Yidong <cyd@stupidchicken.com>
* positions.texi (Excursions): Explain the "save-excursion
defeated by set-buffer" warning.
* buffers.texi (Current Buffer): Copyedits. Don't recommend using
save-excursion. Suggested by Uday S Reddy.
2011-04-01 Stefan Monnier <monnier@iro.umontreal.ca>
* variables.texi (Defining Variables): Mention the new meaning of `defvar'.
......
......@@ -85,43 +85,63 @@ This function returns @code{t} if @var{object} is a buffer,
@cindex changing to another buffer
@cindex current buffer
There are, in general, many buffers in an Emacs session. At any time,
one of them is designated as the @dfn{current buffer}. This is the
buffer in which most editing takes place, because most of the primitives
for examining or changing text in a buffer operate implicitly on the
current buffer (@pxref{Text}). Normally the buffer that is displayed on
the screen in the selected window is the current buffer, but this is not
always so: a Lisp program can temporarily designate any buffer as
current in order to operate on its contents, without changing what is
displayed on the screen.
The way to designate a current buffer in a Lisp program is by calling
@code{set-buffer}. The specified buffer remains current until a new one
is designated.
When an editing command returns to the editor command loop, the
command loop designates the buffer displayed in the selected window as
current, to prevent confusion: the buffer that the cursor is in when
Emacs reads a command is the buffer that the command will apply to.
(@xref{Command Loop}.) Therefore, @code{set-buffer} is not the way to
switch visibly to a different buffer so that the user can edit it. For
that, you must use the functions described in @ref{Displaying Buffers}.
@strong{Warning:} Lisp functions that change to a different current buffer
should not depend on the command loop to set it back afterwards.
Editing commands written in Emacs Lisp can be called from other programs
as well as from the command loop; it is convenient for the caller if
the subroutine does not change which buffer is current (unless, of
course, that is the subroutine's purpose). Therefore, you should
normally use @code{set-buffer} within a @code{save-current-buffer} or
@code{save-excursion} (@pxref{Excursions}) form that will restore the
current buffer when your function is done. Here, as an example, is a
There are, in general, many buffers in an Emacs session. At any
time, one of them is designated the @dfn{current buffer}---the buffer
in which most editing takes place. Most of the primitives for
examining or changing text operate implicitly on the current buffer
(@pxref{Text}).
Normally, the buffer displayed in the selected window is the current
buffer, but this is not always so: a Lisp program can temporarily
designate any buffer as current in order to operate on its contents,
without changing what is displayed on the screen. The most basic
function for designating a current buffer is @code{set-buffer}.
@defun current-buffer
This function returns the current buffer.
@example
@group
(current-buffer)
@result{} #<buffer buffers.texi>
@end group
@end example
@end defun
@defun set-buffer buffer-or-name
This function makes @var{buffer-or-name} the current buffer.
@var{buffer-or-name} must be an existing buffer or the name of an
existing buffer. The return value is the buffer made current.
This function does not display the buffer in any window, so the user
cannot necessarily see the buffer. But Lisp programs will now operate
on it.
@end defun
When an editing command returns to the editor command loop, Emacs
automatically calls @code{set-buffer} on the buffer shown in the
selected window. This is to prevent confusion: it ensures that the
buffer that the cursor is in, when Emacs reads a command, is the
buffer to which that command applies (@pxref{Command Loop}). Thus,
you should not use @code{set-buffer} to switch visibly to a different
buffer; for that, use the functions described in @ref{Displaying
Buffers}.
When writing a Lisp function, do @emph{not} rely on this behavior of
the command loop to restore the current buffer after an operation.
Editing commands can also be called as Lisp functions by other
programs, not just from the command loop; it is convenient for the
caller if the subroutine does not change which buffer is current
(unless, of course, that is the subroutine's purpose).
To operate temporarily on another buffer, put the @code{set-buffer}
within a @code{save-current-buffer} form. Here, as an example, is a
simplified version of the command @code{append-to-buffer}:
@example
@group
(defun append-to-buffer (buffer start end)
"Append to specified buffer the text of the region."
"Append the text of the region to BUFFER."
(interactive "BAppend to buffer: \nr")
(let ((oldbuf (current-buffer)))
(save-current-buffer
......@@ -131,27 +151,36 @@ simplified version of the command @code{append-to-buffer}:
@end example
@noindent
This function binds a local variable to record the current buffer, and
then @code{save-current-buffer} arranges to make it current again.
Next, @code{set-buffer} makes the specified buffer current. Finally,
Here, we bind a local variable to record the current buffer, and then
@code{save-current-buffer} arranges to make it current again later.
Next, @code{set-buffer} makes the specified buffer current, and
@code{insert-buffer-substring} copies the string from the original
current buffer to the specified (and now current) buffer.
If the buffer appended to happens to be displayed in some window,
the next redisplay will show how its text has changed. Otherwise, you
will not see the change immediately on the screen. The buffer becomes
current temporarily during the execution of the command, but this does
not cause it to be displayed.
If you make local bindings (with @code{let} or function arguments) for
a variable that may also have buffer-local bindings, make sure that the
same buffer is current at the beginning and at the end of the local
binding's scope. Otherwise you might bind it in one buffer and unbind
it in another! There are two ways to do this. In simple cases, you may
see that nothing ever changes the current buffer within the scope of the
binding. Otherwise, use @code{save-current-buffer} or
@code{save-excursion} to make sure that the buffer current at the
beginning is current again whenever the variable is unbound.
buffer to the specified (and now current) buffer.
Alternatively, we can use the @code{with-current-buffer} macro:
@example
@group
(defun append-to-buffer (buffer start end)
"Append the text of the region to BUFFER."
(interactive "BAppend to buffer: \nr")
(let ((oldbuf (current-buffer)))
(with-current-buffer (get-buffer-create buffer)
(insert-buffer-substring oldbuf start end))))
@end group
@end example
In either case, if the buffer appended to happens to be displayed in
some window, the next redisplay will show how its text has changed.
If it is not displayed in any window, you will not see the change
immediately on the screen. The command causes the buffer to become
current temporarily, but does not cause it to be displayed.
If you make local bindings (with @code{let} or function arguments)
for a variable that may also have buffer-local bindings, make sure
that the same buffer is current at the beginning and at the end of the
local binding's scope. Otherwise you might bind it in one buffer and
unbind it in another!
Do not rely on using @code{set-buffer} to change the current buffer
back, because that won't do the job if a quit happens while the wrong
......@@ -168,29 +197,9 @@ have been wrong to do this:
@end example
@noindent
Using @code{save-current-buffer}, as we did, handles quitting, errors,
and @code{throw}, as well as ordinary evaluation.
@defun current-buffer
This function returns the current buffer.
@example
@group
(current-buffer)
@result{} #<buffer buffers.texi>
@end group
@end example
@end defun
@defun set-buffer buffer-or-name
This function makes @var{buffer-or-name} the current buffer.
@var{buffer-or-name} must be an existing buffer or the name of an
existing buffer. The return value is the buffer made current.
This function does not display the buffer in any window, so the user
cannot necessarily see the buffer. But Lisp programs will now operate
on it.
@end defun
Using @code{save-current-buffer} or @code{with-current-buffer}, as we
did, correctly handles quitting, errors, and @code{throw}, as well as
ordinary evaluation.
@defspec save-current-buffer body@dots{}
The @code{save-current-buffer} special form saves the identity of the
......
......@@ -645,9 +645,9 @@ higher-level completion features that do use the minibuffer.
@defun try-completion string collection &optional predicate
This function returns the longest common substring of all possible
completions of @var{string} in @var{collection}. The value of
@var{collection} must be a list of strings or symbols, an alist, an
obarray, a hash table, or a completion function (@pxref{Programmed
Completion}).
@var{collection} must be a list of strings, an alist whose keys are
strings or symbols, an obarray, a hash table, or a completion function
(@pxref{Programmed Completion}).
Completion compares @var{string} against each of the permissible
completions specified by @var{collection}. If no permissible
......@@ -658,11 +658,11 @@ to all possible matching completions.
If @var{collection} is an alist (@pxref{Association Lists}), the
permissible completions are the elements of the alist that are either
strings, symbols, or conses whose @sc{car} is a string or symbol.
strings, or conses whose @sc{car} is a string or symbol.
Symbols are converted to strings using @code{symbol-name}. Other
elements of the alist are ignored. (Remember that in Emacs Lisp, the
elements of alists do not @emph{have} to be conses.) In particular, a
list of strings or symbols is allowed, even though we usually do not
list of strings is allowed, even though we usually do not
think of such lists as alists.
@cindex obarray in completion
......@@ -678,7 +678,7 @@ Also, you cannot intern a given symbol in more than one obarray.
If @var{collection} is a hash table, then the keys that are strings
are the possible completions. Other keys are ignored.
You can also use a symbol that is a function as @var{collection}.
You can also use a function as @var{collection}.
Then the function is solely responsible for performing completion;
@code{try-completion} returns whatever this function returns. The
function is called with three arguments: @var{string}, @var{predicate}
......@@ -1632,12 +1632,12 @@ which performs completion according to the rules used in Emacs 21; and
@subsection Programmed Completion
@cindex programmed completion
Sometimes it is not possible to create an alist or an obarray
containing all the intended possible completions. In such a case, you
can supply your own function to compute the completion of a given
string. This is called @dfn{programmed completion}. Emacs uses
programmed completion when completing file names (@pxref{File Name
Completion}), among many other cases.
Sometimes it is not possible or convenient to create an alist or
an obarray containing all the intended possible completions ahead
of time. In such a case, you can supply your own function to compute
the completion of a given string. This is called @dfn{programmed
completion}. Emacs uses programmed completion when completing file
names (@pxref{File Name Completion}), among many other cases.
To use this feature, pass a function as the @var{collection}
argument to @code{completing-read}. The function
......@@ -1665,7 +1665,7 @@ specifies which method to run.
@end itemize
There are currently four methods, i.e. four flag values, one for
each of the four different basic operations:
each of the four different basic operations:
@itemize @bullet
@item
......@@ -1696,14 +1696,6 @@ in the string to complete, and END is the position of the end boundary
in SUFFIX.
@end itemize
It would be consistent and clean for completion functions to allow
lambda expressions (lists that are functions) as well as function
symbols as @var{collection}, but this is impossible. Lists as
completion tables already have other meanings, and it would be
unreliable to treat one differently just because it is also a possible
function. So you must arrange for any function you wish to use for
completion to be encapsulated in a symbol.
@defun completion-table-dynamic function
This function is a convenient way to write a function that can act as
programmed completion function. The argument @var{function} should be
......
......@@ -797,69 +797,72 @@ is zero or less.
@cindex excursion
It is often useful to move point ``temporarily'' within a localized
portion of the program, or to switch buffers temporarily. This is
called an @dfn{excursion}, and it is done with the @code{save-excursion}
special form. This construct initially remembers the identity of the
current buffer, and its values of point and the mark, and restores them
after the completion of the excursion.
The forms for saving and restoring the configuration of windows are
described elsewhere (see @ref{Window Configurations}, and @pxref{Frame
Configurations}). When only the identity of the current buffer needs
to be saved and restored, it is preferable to use
@code{save-current-buffer} instead.
portion of the program. This is called an @dfn{excursion}, and it is
done with the @code{save-excursion} special form. This construct
remembers the initial identity of the current buffer, and its values
of point and the mark, and restores them after the excursion
completes. It is the standard way to move point within one part of a
program and avoid affecting the rest of the program, and is used
thousands of times in the Lisp sources of Emacs.
If you only need to save and restore the identity of the current
buffer, use @code{save-current-buffer} or @code{with-current-buffer}
instead (@pxref{Current Buffer}). If you need to save or restore
window configurations, see the forms described in @ref{Window
Configurations} and in @ref{Frame Configurations}.
@defspec save-excursion body@dots{}
@cindex mark excursion
@cindex point excursion
The @code{save-excursion} special form saves the identity of the current
buffer and the values of point and the mark in it, evaluates
@var{body}, and finally restores the buffer and its saved values of
point and the mark. All three saved values are restored even in case of
an abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
This special form saves the identity of the current buffer and the
values of point and the mark in it, evaluates @var{body}, and finally
restores the buffer and its saved values of point and the mark. All
three saved values are restored even in case of an abnormal exit via
@code{throw} or error (@pxref{Nonlocal Exits}).
The @code{save-excursion} special form is the standard way to move
point within one part of a program and avoid affecting the rest of the
program. It is used more than 4000 times in the Lisp sources
of Emacs.
The value returned by @code{save-excursion} is the result of the last
form in @var{body}, or @code{nil} if no body forms were given.
@end defspec
@code{save-excursion} does not save the values of point and the mark for
other buffers, so changes in other buffers remain in effect after
@code{save-excursion} exits.
Because @code{save-excursion} only saves point and mark for the
buffer that was current at the start of the excursion, any changes
made to point and/or mark in other buffers, during the excursion, will
remain in effect afterward. This frequently leads to unintended
consequences, so the byte compiler warns if you call @code{set-buffer}
during an excursion:
@cindex window excursions
Likewise, @code{save-excursion} does not restore window-buffer
correspondences altered by functions such as @code{switch-to-buffer}.
One way to restore these correspondences, and the selected window, is to
use @code{save-window-excursion} inside @code{save-excursion}
(@pxref{Window Configurations}).
@example
Warning: @code{save-excursion} defeated by @code{set-buffer}
@end example
The value returned by @code{save-excursion} is the result of the last
form in @var{body}, or @code{nil} if no body forms were given.
@noindent
To avoid such problems, you should call @code{save-excursion} only
after setting the desired current buffer, as in the following example:
@example
@group
(save-excursion @var{forms})
@equiv{}
(let ((old-buf (current-buffer))
(old-pnt (point-marker))
@end group
(old-mark (copy-marker (mark-marker))))
(unwind-protect
(progn @var{forms})
(set-buffer old-buf)
@group
(goto-char old-pnt)
(set-marker (mark-marker) old-mark)))
(defun append-string-to-buffer (string buffer)
"Append STRING to the end of BUFFER."
(with-current-buffer buffer
(save-excursion
(goto-char (point-max))
(insert string))))
@end group
@end example
@end defspec
@cindex window excursions
Likewise, @code{save-excursion} does not restore window-buffer
correspondences altered by functions such as @code{switch-to-buffer}.
One way to restore these correspondences, and the selected window, is to
use @code{save-window-excursion} inside @code{save-excursion}
(@pxref{Window Configurations}).
@strong{Warning:} Ordinary insertion of text adjacent to the saved
point value relocates the saved value, just as it relocates all markers.
More precisely, the saved value is a marker with insertion type
@code{nil}. @xref{Marker Insertion Types}. Therefore, when the saved
point value is restored, it normally comes before the inserted text.
point value relocates the saved value, just as it relocates all
markers. More precisely, the saved value is a marker with insertion
type @code{nil}. @xref{Marker Insertion Types}. Therefore, when the
saved point value is restored, it normally comes before the inserted
text.
Although @code{save-excursion} saves the location of the mark, it does
not prevent functions which modify the buffer from setting
......
......@@ -21,6 +21,13 @@ with a prefix argument or by typing C-u C-h C-n.
crt*.o files, if they are in a non-standard location. This is only
used on x86-64 and s390x GNU/Linux architectures.
** The MS-Windows build prefers libpng version 1.14 or later.
Versions of libpng before 1.14 had security issues, so we now
recommend to use version 1.14 or later. Precompiled Windows binaries
require version 1.14 or later. See README.W32 and nt/INSTALL for
details and pointers to URLs where the latest libpng can be
downloaded.
* Changes in Emacs 23.3
** The last-resort backup file `%backup%~' is now written to
......
2011-03-24 Juanma Barranquero <lekktu@gmail.com>
* vc-annotate.el (vc-annotate-show-log-revision-at-line):
Fix typo in docstring.
2011-04-08 Eli Zaretskii <eliz@gnu.org>
* simple.el (list-processes): If async subprocesses are not
......
......@@ -489,7 +489,7 @@ Return a cons (REV . FILENAME)."
"Visit the log of the revision at line.
If the VC backend supports it, only show the log entry for the revision.
If a *vc-change-log* buffer exists and already shows a log for
the file in question, search for the log entry required and move point ."
the file in question, search for the log entry required and move point."
(interactive)
(if (not (equal major-mode 'vc-annotate-mode))
(message "Cannot be invoked outside of a vc annotate buffer")
......
2011-04-08 Svante Signell <svante.signell@telia.com> (tiny change)
* term.c (init_tty): Fix incorrect ifdef placement (Bug#8450).
2011-03-19 Christoph Scholtes <cschol2112@googlemail.com>
* process.c (Fformat_network_address): Doc fix.
2011-04-08 T.V. Raman <tv.raman.tv@gmail.com> (tiny change)
* xml.c (parse_region): Avoid creating spurious whiespace nodes.
......
......@@ -1261,9 +1261,9 @@ at end of BUFFER, unless you specify an output stream or filter
function to handle the output. BUFFER may also be nil, meaning that
this process is not associated with any buffer.
PROGRAM is the program file name. It is searched for in PATH. If
nil, just associate a pty with the buffer. Remaining arguments are
strings to give program as arguments.
PROGRAM is the program file name. It is searched for in `exec-path'
(which see). If nil, just associate a pty with the buffer. Remaining
arguments are strings to give program as arguments.
If you want to separate standard output from standard error, invoke
the command through a shell and redirect one of them using the shell
......
......@@ -3155,13 +3155,12 @@ init_tty (const char *name, const char *terminal_type, int must_succeed)
if we don't have one at the moment. */
fd = emacs_open (name, O_RDWR | O_IGNORE_CTTY | O_NOCTTY, 0);
else
#else
#endif /* O_IGNORE_CTTY */
/* Alas, O_IGNORE_CTTY is a GNU extension that seems to be only
defined on Hurd. On other systems, we need to explicitly
dissociate ourselves from the controlling tty when we want to
open a frame on the same terminal. */
fd = emacs_open (name, O_RDWR | O_NOCTTY, 0);
#endif /* O_IGNORE_CTTY */
tty->name = xstrdup (name);
terminal->name = xstrdup (name);
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment