[Emacs-diffs] trunk r116841: Merge from emacs-24; up to r116832

[Glenn Morris]

------------------------------------------------------------
revno: 116841 [merge]
revision-id: address@hidden
parent: address@hidden
parent: address@hidden
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Sat 2014-03-22 14:44:04 -0700
message:
  Merge from emacs-24; up to r116832
modified:
  doc/lispref/ChangeLog          changelog-20091113204419-o5vbwnq5f7feedwu-6155
  doc/lispref/commands.texi      
commands.texi-20091113204419-o5vbwnq5f7feedwu-6165
  doc/lispref/functions.texi     
functions.texi-20091113204419-o5vbwnq5f7feedwu-6182
  lisp/ChangeLog                 changelog-20091113204419-o5vbwnq5f7feedwu-1432
  lisp/emacs-lisp/package.el     package.el-20100617020707-ybavz666awsxwin6-2
  lisp/w32-common-fns.el         
w32commonfns.el-20120917115700-3at3xhn4to67xnca-4
  test/automated/data/package/archive-contents 
archivecontents-20130627091649-1urk343g07eug5h7-3
  test/automated/package-test.el 
packagetest.el-20130627091655-6mb005jio30t2i3i-1

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2014-03-21 19:04:57 +0000
+++ b/doc/lispref/ChangeLog     2014-03-22 21:44:04 +0000
@@ -1,3 +1,20 @@
+2014-03-22  Glenn Morris  <address@hidden>
+
+       * commands.texi (Defining Commands): List interactive-only values.
+
+2014-03-22  Eli Zaretskii  <address@hidden>
+
+       * functions.texi (Core Advising Primitives): Fix cross-reference
+       in last change.
+
+2014-03-22  Stefan Monnier  <address@hidden>
+
+       * functions.texi (Advising Functions): Explain a bit more how
+       arguments work.
+       (Advice combinators): New node.
+       (Core Advising Primitives): Use it.  Expand description of "depth".
+       (Advising Named Functions): Document limitation of advices on macros.
+
 2014-03-21  Martin Rudalics  <address@hidden>
 
        * frames.texi (Size and Position): In `frame-resize-pixelwise'

=== modified file 'doc/lispref/commands.texi'
--- a/doc/lispref/commands.texi 2014-03-21 07:06:55 +0000
+++ b/doc/lispref/commands.texi 2014-03-22 21:41:31 +0000
@@ -126,7 +126,12 @@
   Sometimes, a function is only intended to be called interactively,
 never directly from Lisp.  In that case, give the function a
 address@hidden @code{interactive-only} property.  This causes the
-byte compiler to warn if the command is called from Lisp.
+byte compiler to warn if the command is called from Lisp.  The value
+of the property can be: a string, which the byte-compiler will
+use directly in its warning (it should end with a period,
+and not start with a capital, e.g. ``use @dots{} instead.''); @code{t};
+any other symbol, which should be an alternative function to use in
+Lisp code.
 
 @menu
 * Using Interactive::     General rules for @code{interactive}.

=== modified file 'doc/lispref/functions.texi'
--- a/doc/lispref/functions.texi        2014-03-18 11:29:33 +0000
+++ b/doc/lispref/functions.texi        2014-03-22 21:44:04 +0000
@@ -1170,9 +1170,10 @@
 (add-function :before (process-filter @var{proc}) #'my-tracing-function)
 @end example
 
-This will cause the process's output to be passed first to
address@hidden and then to the original process filter.
-When you're done with it, you can revert to the untraced behavior with:
+This will cause the process's output to be passed to @code{my-tracing-function}
+before being passed to the original process filter.  @code{my-tracing-function}
+receives the same arguments as the original function.  When you're done with
+it, you can revert to the untraced behavior with:
 
 @example
 (remove-function (process-filter @var{proc}) #'my-tracing-function)
@@ -1191,20 +1192,24 @@
 (advice-add 'display-buffer :around #'his-tracing-function)
 @end example
 
-and when you're tired of seeing this output, you can revert to the untraced
+Here, @code{his-tracing-function} is called instead of the original function
+and receives the original function (additionally to that function's arguments)
+as argument, so it can call it if and when it needs to.
+When you're tired of seeing this output, you can revert to the untraced
 behavior with:
 
 @example
 (advice-remove 'display-buffer #'his-tracing-function)
 @end example
 
-The arguments @code{:before} and @code{:above} used in the above examples
+The arguments @code{:before} and @code{:around} used in the above examples
 specify how the two functions are composed, since there are many different
 ways to do it.  The added function is also called an @emph{advice}.
 
 @menu
 * Core Advising Primitives::    Primitives to Manipulate Advices
 * Advising Named Functions::    Advising Named Functions
+* Advice combinators::          Ways to compose advices
 * Porting old advices::         Adapting code using the old defadvice
 @end menu
 
@@ -1225,104 +1230,9 @@
 received as argument, use @code{advice-eval-interactive-spec}.
 
 @var{where} determines how @var{function} is composed with the
-existing function.  It can be one of the following:
-
address@hidden @code
address@hidden :before
-Call @var{function} before the old function.  Both functions receive the
-same arguments, and the return value of the composition is the return value of
-the old function.  More specifically, the composition of the two functions
-behaves like:
address@hidden
-(lambda (&rest r) (apply @var{function} r) (apply @var{oldfun} r))
address@hidden example
-This is similar to @code{(add-hook @var{hook} @var{function})}, except that it
-applies to single-function hooks rather than normal hooks.
-
address@hidden :after
-Call @var{function} after the old function.  Both functions receive the
-same arguments, and the return value of the composition is the return value of
-the old function.  More specifically, the composition of the two functions
-behaves like:
address@hidden
-(lambda (&rest r) (prog1 (apply @var{oldfun} r) (apply @var{function} r)))
address@hidden example
-This is similar to @code{(add-hook @var{hook} @var{function} nil 'append)},
-except that it applies to single-function hooks rather than normal hooks.
-
address@hidden :override
-This completely replaces the old function with the new one.  The old function
-can of course be recovered if you later call @code{remove-function}.
-
address@hidden :around
-Call @var{function} instead of the old function, but provide the old function
-as an extra argument to @var{function}.  This is the most flexible composition.
-For example, it lets you call the old function with different arguments, or
-within a let-binding, or you can sometimes delegate the work to the old
-function and sometimes override it completely.  More specifically, the
-composition of the two functions behaves like:
address@hidden
-(lambda (&rest r) (apply @var{function} @var{oldfun} r))
address@hidden example
-
address@hidden :before-while
-Call @var{function} before the old function and don't call the old
-function if @var{function} returns @code{nil}.  Both functions receive the
-same arguments, and the return value of the composition is the return value of
-the old function.  More specifically, the composition of the two functions
-behaves like:
address@hidden
-(lambda (&rest r) (and (apply @var{function} r) (apply @var{oldfun} r)))
address@hidden example
-This is reminiscent of @code{(add-hook @var{hook} @var{function})}, when
address@hidden is run via @code{run-hook-with-args-until-failure}.
-
address@hidden :before-until
-Call @var{function} before the old function and only call the old function if
address@hidden returns @code{nil}.  More specifically, the composition of the
-two functions behaves like:
address@hidden
-(lambda (&rest r) (or (apply @var{function} r) (apply @var{oldfun} r)))
address@hidden example
-This is reminiscent of @code{(add-hook @var{hook} @var{function})}, when
address@hidden is run via @code{run-hook-with-args-until-success}.
-
address@hidden :after-while
-Call @var{function} after the old function and only if the old function
-returned address@hidden  Both functions receive the same arguments, and the
-return value of the composition is the return value of @var{function}.
-More specifically, the composition of the two functions behaves like:
address@hidden
-(lambda (&rest r) (and (apply @var{oldfun} r) (apply @var{function} r)))
address@hidden example
-This is reminiscent of @code{(add-hook @var{hook} @var{function} nil 'append)},
-when @var{hook} is run via @code{run-hook-with-args-until-failure}.
-
address@hidden :after-until
-Call @var{function} after the old function and only if the old function
-returned @code{nil}.  More specifically, the composition of the two functions
-behaves like:
address@hidden
-(lambda (&rest r) (or  (apply @var{oldfun} r) (apply @var{function} r)))
address@hidden example
-This is reminiscent of @code{(add-hook @var{hook} @var{function} nil 'append)},
-when @var{hook} is run via @code{run-hook-with-args-until-success}.
-
address@hidden :filter-args
-Call @var{function} first and use the result (which should be a list) as the
-new arguments to pass to the old function.  More specifically, the composition
-of the two functions behaves like:
address@hidden
-(lambda (&rest r) (apply @var{oldfun} (funcall @var{function} r)))
address@hidden example
-
address@hidden :filter-return
-Call the old function first and pass the result to @var{function}.
-More specifically, the composition of the two functions behaves like:
address@hidden
-(lambda (&rest r) (funcall @var{function} (apply @var{oldfun} r)))
address@hidden example
address@hidden table
+existing function, e.g. whether @var{function} should be called before, or
+after the original function.  @xref{Advice combinators}, for the list of
+available ways to compose the two functions.
 
 When modifying a variable (whose name will usually end with @code{-function}),
 you can choose whether @var{function} is used globally or only in the current
@@ -1343,11 +1253,22 @@
 anonymous function.
 
 @item depth
-This specifies where to place the advice, in case several advices are present.
+This specifies how to order the advices, in case several advices are present.
 By default, the depth is 0.  A depth of 100 indicates that this advice should
 be kept as deep as possible, whereas a depth of -100 indicates that it
 should stay as the outermost advice.  When two advices specify the same depth,
 the most recently added advice will be outermost.
+
+For a @code{:before} advice, being outermost means that this advice will be run
+first, before any other advice, whereas being innermost means that it will run
+right before the original function, with no other advice run between itself and
+the original function.  Similarly, for an @code{:after} advice innermost means
+that it will run right after the original function, with no other advice run in
+between, whereas outermost means that it will be run very last after all
+other advices.  An innermost @code{:override} advice will only override the
+original function and other advices will apply to it, whereas an outermost
address@hidden:override} advice will override not only the original function 
but all
+other advices applied to it as well.
 @end table
 @end defmac
 
@@ -1419,8 +1340,10 @@
 functions in Emacs.  (There are currently a few exceptions to this
 convention, but we aim to correct them.)
 
-  Macros can also be advised, in much the same way as functions.
-However, special forms (@pxref{Special Forms}) cannot be advised.
+  Special forms (@pxref{Special Forms}) cannot be advised, however macros can
+be advised, in much the same way as functions.  Of course, this will not affect
+code that has already been macro-expanded, so you need to make sure the advice
+is installed before the macro is expanded.
 
   It is possible to advise a primitive (@pxref{What Is a Function}),
 but one should typically @emph{not} do so, for two reasons.  Firstly,
@@ -1453,6 +1376,119 @@
 and its properties.
 @end defun
 
address@hidden Advice combinators
address@hidden Ways to compose advices
+
+Here are the different possible values for the @var{where} argument of
address@hidden and @code{advice-add}, specifying how the advice
address@hidden and the original function should be composed.
+
address@hidden @code
address@hidden :before
+Call @var{function} before the old function.  Both functions receive the
+same arguments, and the return value of the composition is the return value of
+the old function.  More specifically, the composition of the two functions
+behaves like:
address@hidden
+(lambda (&rest r) (apply @var{function} r) (apply @var{oldfun} r))
address@hidden example
address@hidden(add-function :before @var{funvar} @var{function})} is comparable 
for
+single-function hooks to @code{(add-hook '@var{hookvar} @var{function})} for
+normal hooks.
+
address@hidden :after
+Call @var{function} after the old function.  Both functions receive the
+same arguments, and the return value of the composition is the return value of
+the old function.  More specifically, the composition of the two functions
+behaves like:
address@hidden
+(lambda (&rest r) (prog1 (apply @var{oldfun} r) (apply @var{function} r)))
address@hidden example
address@hidden(add-function :after @var{funvar} @var{function})} is comparable 
for
+single-function hooks to @code{(add-hook '@var{hookvar} @var{function}
+'append)} for normal hooks.
+
address@hidden :override
+This completely replaces the old function with the new one.  The old function
+can of course be recovered if you later call @code{remove-function}.
+
address@hidden :around
+Call @var{function} instead of the old function, but provide the old function
+as an extra argument to @var{function}.  This is the most flexible composition.
+For example, it lets you call the old function with different arguments, or
+many times, or within a let-binding, or you can sometimes delegate the work to
+the old function and sometimes override it completely.  More specifically, the
+composition of the two functions behaves like:
address@hidden
+(lambda (&rest r) (apply @var{function} @var{oldfun} r))
address@hidden example
+
address@hidden :before-while
+Call @var{function} before the old function and don't call the old
+function if @var{function} returns @code{nil}.  Both functions receive the
+same arguments, and the return value of the composition is the return value of
+the old function.  More specifically, the composition of the two functions
+behaves like:
address@hidden
+(lambda (&rest r) (and (apply @var{function} r) (apply @var{oldfun} r)))
address@hidden example
address@hidden(add-function :before-while @var{funvar} @var{function})} is 
comparable
+for single-function hooks to @code{(add-hook '@var{hookvar} @var{function})}
+when @var{hookvar} is run via @code{run-hook-with-args-until-failure}.
+
address@hidden :before-until
+Call @var{function} before the old function and only call the old function if
address@hidden returns @code{nil}.  More specifically, the composition of the
+two functions behaves like:
address@hidden
+(lambda (&rest r) (or (apply @var{function} r) (apply @var{oldfun} r)))
address@hidden example
address@hidden(add-function :before-until @var{funvar} @var{function})} is 
comparable
+for single-function hooks to @code{(add-hook '@var{hookvar} @var{function})}
+when @var{hookvar} is run via @code{run-hook-with-args-until-success}.
+
address@hidden :after-while
+Call @var{function} after the old function and only if the old function
+returned address@hidden  Both functions receive the same arguments, and the
+return value of the composition is the return value of @var{function}.
+More specifically, the composition of the two functions behaves like:
address@hidden
+(lambda (&rest r) (and (apply @var{oldfun} r) (apply @var{function} r)))
address@hidden example
address@hidden(add-function :after-while @var{funvar} @var{function})} is 
comparable
+for single-function hooks to @code{(add-hook '@var{hookvar} @var{function}
+'append)} when @var{hookvar} is run via
address@hidden
+
address@hidden :after-until
+Call @var{function} after the old function and only if the old function
+returned @code{nil}.  More specifically, the composition of the two functions
+behaves like:
address@hidden
+(lambda (&rest r) (or  (apply @var{oldfun} r) (apply @var{function} r)))
address@hidden example
address@hidden(add-function :after-until @var{funvar} @var{function})} is 
comparable
+for single-function hooks to @code{(add-hook '@var{hookvar} @var{function}
+'append)} when @var{hookvar} is run via
address@hidden
+
address@hidden :filter-args
+Call @var{function} first and use the result (which should be a list) as the
+new arguments to pass to the old function.  More specifically, the composition
+of the two functions behaves like:
address@hidden
+(lambda (&rest r) (apply @var{oldfun} (funcall @var{function} r)))
address@hidden example
+
address@hidden :filter-return
+Call the old function first and pass the result to @var{function}.
+More specifically, the composition of the two functions behaves like:
address@hidden
+(lambda (&rest r) (funcall @var{function} (apply @var{oldfun} r)))
address@hidden example
address@hidden table
+
+
 @node Porting old advices
 @subsection Adapting code using the old defadvice
 

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2014-03-22 08:13:46 +0000
+++ b/lisp/ChangeLog    2014-03-22 21:44:04 +0000
@@ -1,3 +1,13 @@
+2014-03-22  Dmitry Gutov  <address@hidden>
+
+       * emacs-lisp/package.el (package-desc): Use the contents of the
+       quoted form, not its cdr.  (Bug#16873)
+
+2014-03-22  Juanma Barranquero  <address@hidden>
+
+       * w32-common-fns.el (x-selection-owner-p): Add empty docstring for the
+       benefit of doc.c; change parameter profile to match the X function.
+
 2014-03-22  Leo Liu  <address@hidden>
 
        * help.el (temp-buffer-setup-hook): Remove help-mode-setup.

=== modified file 'lisp/emacs-lisp/package.el'
--- a/lisp/emacs-lisp/package.el        2014-03-21 06:06:52 +0000
+++ b/lisp/emacs-lisp/package.el        2014-03-22 08:43:30 +0000
@@ -334,7 +334,7 @@
                                  (when value
                                    (push (cons (car rest-plist)
                                                (if (eq (car-safe value) 'quote)
-                                                   (cdr value)
+                                                   (cadr value)
                                                  value))
                                          alist))))
                              (setq rest-plist (cddr rest-plist)))

=== modified file 'lisp/w32-common-fns.el'
--- a/lisp/w32-common-fns.el    2014-02-10 17:05:52 +0000
+++ b/lisp/w32-common-fns.el    2014-03-22 00:24:00 +0000
@@ -84,9 +84,10 @@
   (get 'x-selections (or type 'PRIMARY)))
 
 ;; x-selection-owner-p is used in simple.el
-(defun x-selection-owner-p (&optional type)
-  (and (memq type '(nil PRIMARY SECONDARY))
-       (get 'x-selections (or type 'PRIMARY))))
+(defun x-selection-owner-p (&optional selection _terminal)
+  "" ; placeholder for doc.c
+  (and (memq selection '(nil PRIMARY SECONDARY))
+       (get 'x-selections (or selection 'PRIMARY))))
 
 ;; The "Windows" keys on newer keyboards bring up the Start menu
 ;; whether you want it or not - make Emacs ignore these keystrokes

=== modified file 'test/automated/data/package/archive-contents'
--- a/test/automated/data/package/archive-contents      2014-03-21 06:06:52 
+0000
+++ b/test/automated/data/package/archive-contents      2014-03-22 08:43:30 
+0000
@@ -2,7 +2,8 @@
  (simple-single .
                 [(1 3)
                  nil "A single-file package with no dependencies" single
-                 ((:url . "http://doodles.au";))])
+                 ((:url . "http://doodles.au";)
+                  (:keywords quote ("frobnicate")))])
  (simple-depend .
                 [(1 0)
                  ((simple-single (1 3))) "A single-file package with a 
dependency." single])

=== modified file 'test/automated/package-test.el'
--- a/test/automated/package-test.el    2014-03-21 06:06:52 +0000
+++ b/test/automated/package-test.el    2014-03-22 08:43:30 +0000
@@ -326,6 +326,7 @@
      (should (search-forward "Summary: A single-file package with no 
dependencies"
                              nil t))
      (should (search-forward "Homepage: http://doodles.au"; nil t))
+     (should (search-forward "Keywords: frobnicate"))
      ;; No description, though. Because at this point we don't know
      ;; what archive the package originated from, and we don't have
      ;; its readme file saved.