Merge changes from emacs-23 branch

12 files changed, 201 insertions, 157 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index b25e6ce219f..47aa395c730 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,7 @@
+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
diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index 405ee26312f..7777aacf0e5 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -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.
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 445e94a0c43..784f62dc4cc 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,18 @@
+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'.
diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index 07889cdbaa3..0f9de74c948 100644
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -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
diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index 07975e64b35..acc68b0aafa 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -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
diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi
index a44cd1fbcc7..1124d58ebcc 100644
--- a/doc/lispref/positions.texi
+++ b/doc/lispref/positions.texi
@@ -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
diff --git a/etc/NEWS.23 b/etc/NEWS.23
index 3e7a364ffd0..458e2bb3d32 100644
--- a/etc/NEWS.23
+++ b/etc/NEWS.23
@@ -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
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index d93dd27477a..551e12f94ba 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,8 @@
+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
diff --git a/lisp/vc/vc-annotate.el b/lisp/vc/vc-annotate.el
index 479dbb5caea..271fce12429 100644
--- a/lisp/vc/vc-annotate.el
+++ b/lisp/vc/vc-annotate.el
@@ -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")
diff --git a/src/ChangeLog b/src/ChangeLog
index dc06f81d972..efacbbc4583 100644
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,3 +1,11 @@
+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.
diff --git a/src/process.c b/src/process.c
index 4476014edfa..6cddbf6d1a9 100644
--- a/src/process.c
+++ b/src/process.c
@@ -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
diff --git a/src/term.c b/src/term.c
index 39c9592e28f..9be9950d5eb 100644
--- a/src/term.c
+++ b/src/term.c
@@ -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);