[Emacs-diffs] /srv/bzr/emacs/trunk r103872: Merge changes from emacs-23 branch

[Chong Yidong]

------------------------------------------------------------
revno: 103872 [merge]
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Fri 2011-04-08 14:54:05 -0400
message:
  Merge changes from emacs-23 branch
modified:
  doc/emacs/ChangeLog
  doc/emacs/display.texi
  doc/lispref/ChangeLog
  doc/lispref/buffers.texi
  doc/lispref/minibuf.texi
  doc/lispref/positions.texi
  etc/NEWS.23
  lisp/ChangeLog
  lisp/vc/vc-annotate.el
  src/ChangeLog
  src/process.c
  src/term.c

=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog       2011-04-06 12:18:10 +0000
+++ b/doc/emacs/ChangeLog       2011-04-08 18:53:26 +0000
@@ -1,3 +1,7 @@
+2011-03-26  Chong Yidong  <address@hidden>
+
+       * display.texi (Auto Scrolling): Fix scroll-up/scroll-down confusion.
+
 2011-03-30  Eli Zaretskii  <address@hidden>
 
        * display.texi (Auto Scrolling): Document the limit of 100 lines

=== modified file 'doc/emacs/display.texi'
--- a/doc/emacs/display.texi    2011-03-30 20:59:42 +0000
+++ b/doc/emacs/display.texi    2011-04-08 18:53:26 +0000
@@ -206,16 +206,18 @@
 @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,
address@hidden, 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
address@hidden, 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.

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2011-04-06 12:18:10 +0000
+++ b/doc/lispref/ChangeLog     2011-04-08 18:53:26 +0000
@@ -1,3 +1,18 @@
+2011-03-21  Stefan Monnier  <address@hidden>
+
+       * 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  <address@hidden>
+
+       * 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  <address@hidden>
 
        * variables.texi (Defining Variables): Mention the new meaning of 
`defvar'.

=== modified file 'doc/lispref/buffers.texi'
--- a/doc/lispref/buffers.texi  2011-01-25 04:08:28 +0000
+++ b/doc/lispref/buffers.texi  2011-04-08 18:53:26 +0000
@@ -85,43 +85,63 @@
 @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
address@hidden  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
address@hidden (@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}.
+
address@hidden current-buffer
+This function returns the current buffer.
+
address@hidden
address@hidden
+(current-buffer)
+     @result{} #<buffer buffers.texi>
address@hidden group
address@hidden example
address@hidden defun
+
address@hidden set-buffer buffer-or-name
+This function makes @var{buffer-or-name} the current buffer.
address@hidden 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.
address@hidden 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 @@
 @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
address@hidden 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
address@hidden 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:
+
address@hidden
address@hidden
+(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))))
address@hidden group
address@hidden 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 @@
 @end example
 
 @noindent
-Using @code{save-current-buffer}, as we did, handles quitting, errors,
-and @code{throw}, as well as ordinary evaluation.
-
address@hidden current-buffer
-This function returns the current buffer.
-
address@hidden
address@hidden
-(current-buffer)
-     @result{} #<buffer buffers.texi>
address@hidden group
address@hidden example
address@hidden defun
-
address@hidden set-buffer buffer-or-name
-This function makes @var{buffer-or-name} the current buffer.
address@hidden 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.
address@hidden 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 address@hidden
 The @code{save-current-buffer} special form saves the identity of the

=== modified file 'doc/lispref/minibuf.texi'
--- a/doc/lispref/minibuf.texi  2011-02-27 22:10:48 +0000
+++ b/doc/lispref/minibuf.texi  2011-04-08 18:53:26 +0000
@@ -645,9 +645,9 @@
 @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
address@hidden must be a list of strings or symbols, an alist, an
-obarray, a hash table, or a completion function (@pxref{Programmed
-Completion}).
address@hidden 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 @@
 
 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 @@
 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 @@
 @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 @@
 @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 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

=== modified file 'doc/lispref/positions.texi'
--- a/doc/lispref/positions.texi        2011-01-25 04:08:28 +0000
+++ b/doc/lispref/positions.texi        2011-04-08 18:53:26 +0000
@@ -797,69 +797,72 @@
 @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.
+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.
 
-  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
address@hidden instead.
+  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 address@hidden
 @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
address@hidden, 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.
-
address@hidden does not save the values of point and the mark for
-other buffers, so changes in other buffers remain in effect after
address@hidden 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
address@hidden or error (@pxref{Nonlocal Exits}).
+
+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.
address@hidden defspec
+
+  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:
+
address@hidden
+Warning: @code{save-excursion} defeated by @code{set-buffer}
address@hidden example
+
address@hidden
+To avoid such problems, you should call @code{save-excursion} only
+after setting the desired current buffer, as in the following example:
+
address@hidden
address@hidden
+(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))))
address@hidden group
address@hidden example
 
 @cindex window excursions
-Likewise, @code{save-excursion} does not restore window-buffer
+  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}).
 
-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.
-
address@hidden
address@hidden
-(save-excursion @var{forms})
address@hidden
-(let ((old-buf (current-buffer))
-      (old-pnt (point-marker))
address@hidden group
-      (old-mark (copy-marker (mark-marker))))
-  (unwind-protect
-      (progn @var{forms})
-    (set-buffer old-buf)
address@hidden
-    (goto-char old-pnt)
-    (set-marker (mark-marker) old-mark)))
address@hidden group
address@hidden example
address@hidden defspec
-
   @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
address@hidden  @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

=== modified file 'etc/NEWS.23'
--- a/etc/NEWS.23       2011-03-03 08:03:01 +0000
+++ b/etc/NEWS.23       2011-04-08 18:53:26 +0000
@@ -21,6 +21,13 @@
 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

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2011-04-08 17:08:17 +0000
+++ b/lisp/ChangeLog    2011-04-08 18:53:26 +0000
@@ -1,3 +1,8 @@
+2011-03-24  Juanma Barranquero  <address@hidden>
+
+       * vc-annotate.el (vc-annotate-show-log-revision-at-line):
+       Fix typo in docstring.
+
 2011-04-08  Eli Zaretskii  <address@hidden>
 
        * simple.el (list-processes): If async subprocesses are not

=== modified file 'lisp/vc/vc-annotate.el'
--- a/lisp/vc/vc-annotate.el    2011-01-25 04:08:28 +0000
+++ b/lisp/vc/vc-annotate.el    2011-04-08 18:53:26 +0000
@@ -489,7 +489,7 @@
   "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")

=== modified file 'src/ChangeLog'
--- a/src/ChangeLog     2011-04-08 16:15:30 +0000
+++ b/src/ChangeLog     2011-04-08 18:53:26 +0000
@@ -1,3 +1,11 @@
+2011-04-08  Svante Signell  <address@hidden>  (tiny change)
+
+       * term.c (init_tty): Fix incorrect ifdef placement (Bug#8450).
+
+2011-03-19  Christoph Scholtes  <address@hidden>
+
+       * process.c (Fformat_network_address): Doc fix.
+
 2011-04-08  T.V. Raman  <address@hidden>  (tiny change)
 
        * xml.c (parse_region): Avoid creating spurious whiespace nodes.

=== modified file 'src/process.c'
--- a/src/process.c     2011-04-06 21:55:08 +0000
+++ b/src/process.c     2011-04-08 18:53:26 +0000
@@ -1261,9 +1261,9 @@
 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

=== modified file 'src/term.c'
--- a/src/term.c        2011-04-06 04:58:58 +0000
+++ b/src/term.c        2011-04-08 18:53:26 +0000
@@ -3155,13 +3155,12 @@
          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);