Merge from trunk.

39 files changed, 860 insertions, 769 deletions

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 5ef50e0548f..f26643ea5cf 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,189 @@
+2012-11-17  Andreas Politz  <politza@fh-trier.de>
+
+        * ibuffer.el (ibuffer-mark-forward, ibuffer-unmark-forward)
+        (ibuffer-unmark-backward, ibuffer-mark-interactive): Support plain
+        prefix and negative numeric prefix args (Bug#12795).
+
+2012-11-17  Stephen Berman  <stephen.berman@gmx.net>
+
+        * play/gamegrid.el (gamegrid-add-score-with-update-game-score-1):
+        Don't signal an error with a score that is too low to add to the
+        list of top scores. (Bug#12779)
+
+2012-11-17  Chong Yidong  <cyd@gnu.org>
+
+        * help-mode.el (help-xref-interned): End on point-min (Bug#12737).
+
+        * filecache.el (file-cache-add-file): Handle relative file name in
+        the argument (Bug#12694).
+
+2012-11-16  Jürgen Hötzel  <juergen@archlinux.org>  (tiny change)
+
+        * eshell/em-unix.el (eshell/mkdir): Handle "--parents" (bug#12897).
+
+2012-11-16  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * emacs-lisp/advice.el (ad-make-advised-definition): Improve last fix.
+
+        * emacs-lisp/cl-lib.el: Set more meaningful version number.
+
+2012-11-16  Martin Rudalics  <rudalics@gmx.at>
+
+        * window.el (enlarge-window, shrink-window): Don't mention return
+        value in doc-string (Bug#12896).
+        (window--display-buffer): Don't resize frames - it won't work
+        with all window managers and defeat pop-up-frame-alist.
+        (display-buffer-alist): In doc-string explain that CONDITION can
+        be a function and which arguments are passed to it (Bug#12854).
+        (display-buffer-assq-regexp): New argument ACTION.  Handle lambda
+        expressions (Bug#12854).
+        (display-buffer): Pass ACTION argument to
+        display-buffer-assq-regexp.
+
+2012-11-16  Glenn Morris  <rgm@gnu.org>
+
+        * window.el (fit-frame-to-buffer-bottom-margin)
+        (fit-frame-to-buffer, fit-window-to-buffer): Doc fixes.
+
+        * faces.el (face-underline-p): Use face-attribute-specified-or.
+
+2012-11-16  Juanma Barranquero  <lekktu@gmail.com>
+
+        * emacs-lisp/cl-macs.el (cl-loop, cl-do, cl-do*): Doc fixes.
+
+2012-11-16  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * emacs-lisp/cl-macs.el (cl-flet, cl-flet*): Fix docstring (bug#12895).
+
+2012-11-16  Glenn Morris  <rgm@gnu.org>
+
+        * eshell/em-cmpl.el (eshell-pcomplete): New command.  (Bug#12838)
+        (eshell-cmpl-initialize): Bind eshell-pcomplete to TAB, C-i.
+
+        * faces.el (face-underline-p): Doc fix.  Handle :underline being
+        things other than `t' (a string, a list).
+        (face-inverse-video-p): Doc fix.
+        (set-face-underline): Rename it back from set-face-underline-p.
+        Doc fix.  Allow interactive input of values other than t.
+        (read-face-attribute): Apply formatting to :underline,
+        since like :box and :stipple it can take list values.
+
+        * term.el (ansi-term): Don't let C-x escape-char binding
+        clobber the more standard C-c binding.  (Bug#12842)
+
+        * subr.el (set-temporary-overlay-map): Doc fix.
+
+2012-11-16  Martin Rudalics  <rudalics@gmx.at>
+
+        * window.el (record-window-buffer)
+        (display-buffer-record-window): When copying the markers to
+        window-point preserve window-point-insertion-type. (Bug#12588)
+
+2012-11-16  Glenn Morris  <rgm@gnu.org>
+
+        * emacs-lisp/eieio-datadebug.el (eieio-debug-methodinvoke):
+        * net/tramp-gvfs.el (tramp-gvfs-dbus-event-error):
+        Use new names for hooks rather than obsolete aliases.
+
+2012-11-15  Daniel Colascione  <dancol@dancol.org>
+
+        * term/w32-win.el (w32-handle-dropped-file): Use a "file://"
+        prefix instead of "file:" so that when FILE-NAME begins with "//",
+        as it does when the target file is on a network share, url-handler
+        isn't confused.
+
+2012-11-15  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * emacs-lisp/advice.el (ad-definition-type): Make sure we don't use
+        a preactivated advice from an old advice.el; they're not compatible!
+
+2012-11-15  Katsumi Yamaoka  <yamaoka@jpl.org>
+
+        * emacs-lisp/nadvice.el (advice--make-interactive-form):
+        Fix string-spec case.
+
+        * emacs-lisp/advice.el (ad-make-advised-definition): Fix undefined case.
+
+2012-11-15  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * emacs-lisp/nadvice.el: Add buffer-local support to add-function.
+        (advice--buffer-local-function-sample): New var.
+        (advice--set-buffer-local, advice--buffer-local): New functions.
+        (add-function, remove-function): Use them.
+
+2012-11-15  Drew Adams  <drew.adams@oracle.com>
+
+        * imenu.el (imenu--split-submenus): Use imenu--subalist-p (bug#12717).
+
+2012-11-15  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * emacs-lisp/cl-macs.el (cl--transform-lambda): Defend against
+        potential binding of print-gensym to t, and prettify (back)quotes in
+        case they appear in args's default values (bug#12884).
+
+2012-11-14  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * emacs-lisp/nadvice.el: Add around advice for interactive specs.
+        (advice-eval-interactive-spec): New function.
+        (advice--make-interactive-form): Support around advice (bug#12844).
+
+2012-11-14  Dmitry Gutov  <dgutov@yandex.ru>
+
+        * progmodes/ruby-mode.el (ruby-expr-beg): Make heredoc detection
+        more strict.  Add docstring.
+        (ruby-expression-expansion-re): Extract from
+        `ruby-match-expression-expansion'.
+        (ruby-syntax-propertize-function): After everything else, search
+        for expansions in string literals, mark their insides as
+        whitespace syntax and save match data for font-lock.
+        (ruby-font-lock-keywords): Use the 2nd group from expression
+        expansion matches.
+        (ruby-match-expression-expansion): Use the match data saved to the
+        text property in ruby-syntax-propertize-function.
+
+2012-11-14  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * emacs-lisp/gv.el (setf): Fix debug spec for multiple assignments
+        (bug#12879).
+
+2012-11-13  Dmitry Gutov  <dgutov@yandex.ru>
+
+        * progmodes/ruby-mode.el (ruby-move-to-block): Looks for a block
+        start/end keyword a bit harder.  Works with different values of N.
+        Add more comments.
+        (ruby-end-of-block): Update accordingly.
+
+2012-11-13  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * woman.el (woman-file-name): Don't mess with unread-command-events
+        (bug#12861).
+
+        * emacs-lisp/advice.el: Layer on top of nadvice.el.
+        Remove out of date self-require hack.
+        (ad-do-advised-functions): Use simple `dolist'.
+        (ad-advice-name, ad-advice-protected, ad-advice-enabled)
+        (ad-advice-definition): Redefine as functions.
+        (ad-advice-classes): Move before first use.
+        (ad-make-origname, ad-set-orig-definition, ad-clear-orig-definition)
+        (ad-make-mapped-call, ad-make-advised-docstring,ad-make-plain-docstring)
+        (ad--defalias-fset): Remove functions.
+        (ad-make-advicefunname, ad-clear-advicefunname-definition): New funs.
+        (ad-get-orig-definition): Rewrite.
+        (ad-make-advised-definition-docstring): Change base docstring.
+        (ad-real-orig-definition): Rewrite.
+        (ad-map-arglists): Change name of called function.
+        (ad--make-advised-docstring): Redirect `function' from ad-Advice-...
+        (ad-make-advised-definition): Simplify.
+        (ad-assemble-advised-definition): Tweak for new calling context.
+        (ad-activate-advised-definition): Setup ad-Advice-* i.s.o ad-Orig-*.
+        (ad--defalias-fset): Rename from ad-handle-definition.  Make it set the
+        function and call ad-activate if needed.
+        (ad-activate, ad-deactivate): Don't call ad-handle-definition any more.
+        (ad-recover): Clear ad-Advice-* instead of ad-Orig-*.
+        (ad-compile-function): Compile ad-Advice-*.
+        (ad-activate-on-top-level, ad-with-auto-activation-disabled): Remove.
+        (ad-start-advice, ad-stop-advice): Remove.
+
 2012-11-13  Dmitry Gutov  <dgutov@yandex.ru>
 
         * progmodes/ruby-mode.el (ruby-add-log-current-method): Print the
diff --git a/lisp/arc-mode.el b/lisp/arc-mode.el
index cebd4302d0c..9fc91a242d2 100644
--- a/lisp/arc-mode.el
+++ b/lisp/arc-mode.el
@@ -96,7 +96,7 @@
 ;;
 ;; archive-mode-hook
 ;; archive-foo-mode-hook
-;; archive-extract-hooks
+;; archive-extract-hook
 
 ;;; Code:
 
diff --git a/lisp/cedet/ChangeLog b/lisp/cedet/ChangeLog
index 755f4c8159b..a01ce4c30a3 100644
--- a/lisp/cedet/ChangeLog
+++ b/lisp/cedet/ChangeLog
@@ -1,3 +1,24 @@
+2012-11-16  David Engster  <deng@randomsample.de>
+
+        * semantic/symref/list.el (semantic-symref-symbol): Use
+        `semantic-complete-read-tag-project' instead of
+        `semantic-complete-read-tag-buffer-deep', since the latter is not
+        working correctly.
+
+        * semantic/symref.el (semantic-symref-result-get-tags): Use
+        `find-buffer-visiting' to follow symbolic links.
+
+        * semantic/fw.el (semantic-find-file-noselect): Always set
+        `enable-local-variables' to `:safe' when loading files.
+
+2012-11-16  Glenn Morris  <rgm@gnu.org>
+
+        * semantic/lex-spp.el (semantic-lex-spp-lex-text-string):
+        * semantic/util.el (semantic-describe-buffer):
+        * semantic/bovine/c.el (semantic-c-parse-lexical-token)
+        (semantic-default-c-setup):
+        Use new names for hooks rather than obsolete aliases.
+
 2012-11-13  Stefan Monnier  <monnier@iro.umontreal.ca>
 
         * semantic/mru-bookmark.el (semantic-mru-bookmark-mode):
diff --git a/lisp/cedet/semantic/bovine/c.el b/lisp/cedet/semantic/bovine/c.el
index 02ad6e05d1a..a3d57108d1d 100644
--- a/lisp/cedet/semantic/bovine/c.el
+++ b/lisp/cedet/semantic/bovine/c.el
@@ -931,8 +931,8 @@ the regular parser."
           (setq semantic-new-buffer-fcn-was-run t)
           (semantic-lex-init)
           (semantic-clear-toplevel-cache)
-          (remove-hook 'semantic-lex-reset-hooks 'semantic-lex-spp-reset-hook
-                       t)
+          (remove-hook 'semantic-lex-reset-functions
+                       'semantic-lex-spp-reset-hook t)
           )
         ;; Get the macro symbol table right.
         (setq semantic-lex-spp-dynamic-macro-symbol-obarray spp-syms)
@@ -2073,7 +2073,7 @@ actually in their parent which is not accessible.")
         )
 
   (setq semantic-lex-analyzer #'semantic-c-lexer)
-  (add-hook 'semantic-lex-reset-hooks 'semantic-lex-spp-reset-hook nil t)
+  (add-hook 'semantic-lex-reset-functions 'semantic-lex-spp-reset-hook nil t)
   (when (eq major-mode 'c++-mode)
     (add-to-list 'semantic-lex-c-preprocessor-symbol-map '("__cplusplus" . "")))
   )
diff --git a/lisp/cedet/semantic/fw.el b/lisp/cedet/semantic/fw.el
index 5a12047eb76..14ffc808c44 100644
--- a/lisp/cedet/semantic/fw.el
+++ b/lisp/cedet/semantic/fw.el
@@ -421,14 +421,7 @@ into `mode-local-init-hook'." file filename)
          ;; Don't prompt to insert a template if we visit an empty file
          (auto-insert nil)
          ;; We don't want emacs to query about unsafe local variables
-         (enable-local-variables
-          (if (featurep 'xemacs)
-              ;; XEmacs only has nil as an option?
-              nil
-            ;; Emacs 23 has the spiffy :safe option, nil otherwise.
-            (if (>= emacs-major-version 22)
-                nil
-              :safe)))
+         (enable-local-variables :safe)
          ;; ... or eval variables
          (enable-local-eval nil)
          )
diff --git a/lisp/cedet/semantic/lex-spp.el b/lisp/cedet/semantic/lex-spp.el
index 406f2900563..ad366c2b94f 100644
--- a/lisp/cedet/semantic/lex-spp.el
+++ b/lisp/cedet/semantic/lex-spp.el
@@ -30,7 +30,7 @@
 ;; If you use SPP in your language, be sure to specify this in your
 ;; semantic language setup function:
 ;;
-;; (add-hook 'semantic-lex-reset-hooks 'semantic-lex-spp-reset-hook nil t)
+;; (add-hook 'semantic-lex-reset-functions 'semantic-lex-spp-reset-hook nil t)
 ;;
 ;;
 ;; Special Lexical Tokens:
@@ -947,8 +947,8 @@ and variable state from the current buffer."
             (setq semantic-new-buffer-fcn-was-run t)
             (semantic-lex-init)
             (semantic-clear-toplevel-cache)
-            (remove-hook 'semantic-lex-reset-hooks 'semantic-lex-spp-reset-hook
-                         t)
+            (remove-hook 'semantic-lex-reset-functions
+                         'semantic-lex-spp-reset-hook t)
             ))
 
         ;; Second Cheat: copy key variables regarding macro state from the
diff --git a/lisp/cedet/semantic/symref.el b/lisp/cedet/semantic/symref.el
index 540c766cc94..ad897680d7f 100644
--- a/lisp/cedet/semantic/symref.el
+++ b/lisp/cedet/semantic/symref.el
@@ -356,7 +356,7 @@ already."
           (lambda (hit)
             (let* ((line (car hit))
                    (file (cdr hit))
-                   (buff (get-file-buffer file))
+                   (buff (find-buffer-visiting file))
                    (tag nil)
                    )
               (cond
diff --git a/lisp/cedet/semantic/symref/list.el b/lisp/cedet/semantic/symref/list.el
index 55ccf1c103f..729bd8e153c 100644
--- a/lisp/cedet/semantic/symref/list.el
+++ b/lisp/cedet/semantic/symref/list.el
@@ -69,7 +69,7 @@ current project to find references to the input SYM.  The
 references are organized by file and the name of the function
 they are used in.
 Display the references in `semantic-symref-results-mode'."
-  (interactive (list (semantic-tag-name (semantic-complete-read-tag-buffer-deep
+  (interactive (list (semantic-tag-name (semantic-complete-read-tag-project
                                          "Symrefs for: "))))
   (semantic-fetch-tags)
   (let ((res nil)
diff --git a/lisp/cedet/semantic/util.el b/lisp/cedet/semantic/util.el
index 65201c4fd12..f3d30f6af5c 100644
--- a/lisp/cedet/semantic/util.el
+++ b/lisp/cedet/semantic/util.el
@@ -280,7 +280,7 @@ If TAG is not specified, use the tag at point."
                       semantic-parser-name
                       semantic-parse-tree-state
                       semantic-lex-analyzer
-                      semantic-lex-reset-hooks
+                      semantic-lex-reset-functions
                       semantic-lex-syntax-modifications
                       )))
           (dolist (V vars)
diff --git a/lisp/emacs-lisp/advice.el b/lisp/emacs-lisp/advice.el
index ecaf6861a6c..c2ebb3bbdc6 100644
--- a/lisp/emacs-lisp/advice.el
+++ b/lisp/emacs-lisp/advice.el
@@ -47,14 +47,12 @@
 ;; @ Highlights:
 ;; =============
 ;; - Clean definition of multiple, named before/around/after advices
-;;   for functions, macros, subrs and special forms
+;;   for functions and macros.
 ;; - Full control over the arguments an advised function will receive,
 ;;   the binding environment in which it will be executed, as well as the
 ;;   value it will return.
-;; - Allows re/definition of interactive behavior for functions and subrs
-;; - Every piece of advice can have its documentation string which will be
-;;   combined with the original documentation of the advised function at
-;;   call-time of `documentation' for proper command-key substitution.
+;; - Allows re/definition of interactive behavior for commands.
+;; - Every piece of advice can have its documentation string.
 ;; - The execution of every piece of advice can be protected against error
 ;;   and non-local exits in preceding code or advices.
 ;; - Simple argument access either by name, or, more portable but as
@@ -63,7 +61,7 @@
 ;;   version of a function.
 ;; - Advised functions can be byte-compiled either at file-compile time
 ;;   (see preactivation) or activation time.
-;; - Separation of advice definition and activation
+;; - Separation of advice definition and activation.
 ;; - Forward advice is possible, that is
 ;;   as yet undefined or autoload functions can be advised without having to
 ;;   preload the file in which they are defined.
@@ -77,7 +75,7 @@
 ;; - En/disablement mechanism allows the use of  different "views" of advised
 ;;   functions depending on what pieces of advice are currently en/disabled
 ;; - Provides manipulation mechanisms for sets of advised functions via
-;;   regular expressions that match advice names
+;;   regular expressions that match advice names.
 
 ;; @ Overview, or how to read this file:
 ;; =====================================
@@ -113,23 +111,12 @@
 ;; others come from the various Lisp advice mechanisms I've come across
 ;; so far, and a few are simply mine.
 
-;; @ Comments, suggestions, bug reports:
-;; =====================================
-;; If you find any bugs, have suggestions for new advice features, find the
-;; documentation wrong, confusing, incomplete, or otherwise unsatisfactory,
-;; have any questions about Advice, or have otherwise enlightening
-;; comments feel free to send me email at <hans@cs.buffalo.edu>.
-
 ;; @ Safety Rules and Emergency Exits:
 ;; ===================================
 ;; Before we begin: CAUTION!!
 ;; Advice provides you with a lot of rope to hang yourself on very
 ;; easily accessible trees, so, here are a few important things you
-;; should know: Once Advice has been started with `ad-start-advice'
-;; (which happens automatically when you load this file), it
-;; generates an advised definition of the `documentation' function, and
-;; it will enable automatic advice activation when functions get defined.
-;; All of this can be undone at any time with `M-x ad-stop-advice'.
+;; should know:
 ;;
 ;; If you experience any strange behavior/errors etc. that you attribute to
 ;; Advice or to some ill-advised function do one of the following:
@@ -137,45 +124,37 @@
 ;; - M-x ad-deactivate FUNCTION (if you have a definite suspicion what
 ;;                               function gives you problems)
 ;; - M-x ad-deactivate-all      (if you don't have a clue what's going wrong)
-;; - M-x ad-stop-advice         (if you think the problem is related to the
-;;                               advised functions used by Advice itself)
 ;; - M-x ad-recover-normality   (for real emergencies)
 ;; - If none of the above solves your Advice-related problem go to another
 ;;   terminal, kill your Emacs process and send me some hate mail.
 
-;; The first three measures have restarts, i.e., once you've figured out
+;; The first two measures have restarts, i.e., once you've figured out
 ;; the problem you can reactivate advised functions with either `ad-activate',
-;; `ad-activate-all', or `ad-start-advice'. `ad-recover-normality' unadvises
+;; or `ad-activate-all'.  `ad-recover-normality' unadvises
 ;; everything so you won't be able to reactivate any advised functions, you'll
 ;; have to stick with their standard incarnations for the rest of the session.
 
-;; IMPORTANT: With Advice loaded always do `M-x ad-deactivate-all' before
-;; you byte-compile a file, because advised special forms and macros can lead
-;; to unwanted compilation results. When you are done compiling use
-;; `M-x ad-activate-all' to go back to the advised state of all your
-;; advised functions.
-
 ;; RELAX: Advice is pretty safe even if you are oblivious to the above.
 ;; I use it extensively and haven't run into any serious trouble in a long
-;; time. Just wanted you to be warned.
+;; time.  Just wanted you to be warned.
 
 ;; @ Customization:
 ;; ================
 
 ;; Look at the documentation of `ad-redefinition-action' for possible values
-;; of this variable. Its default value is `warn' which will print a warning
+;; of this variable.  Its default value is `warn' which will print a warning
 ;; message when an already defined advised function gets redefined with a
 ;; new original definition and de/activated.
 
 ;; Look at the documentation of `ad-default-compilation-action' for possible
-;; values of this variable. Its default value is `maybe' which will compile
+;; values of this variable.  Its default value is `maybe' which will compile
 ;; advised definitions during activation in case the byte-compiler is already
-;; loaded. Otherwise, it will leave them uncompiled.
+;; loaded.  Otherwise, it will leave them uncompiled.
 
 ;; @ Motivation:
 ;; =============
 ;; Before I go on explaining how advice works, here are four simple examples
-;; how this package can be used. The first three are very useful, the last one
+;; how this package can be used.  The first three are very useful, the last one
 ;; is just a joke:
 
 ;;(defadvice switch-to-buffer (before existing-buffers-only activate)
@@ -206,13 +185,12 @@
 
 ;; @ Advice documentation:
 ;; =======================
-;; Below is general documentation of the various features of advice. For more
+;; Below is general documentation of the various features of advice.  For more
 ;; concrete examples check the corresponding sections in the tutorial part.
 
 ;; @@ Terminology:
 ;; ===============
 ;; - Emacs: Emacs as released by the GNU Project
-;; - jwz: Jamie Zawinski - creator of the byte-compiler used in v19s.
 ;; - Advice: The name of this package.
 ;; - advices: Short for "pieces of advice".
 
@@ -236,22 +214,22 @@
 ;; <name> is the name of the advice which has to be a non-nil symbol.
 ;; Names uniquely identify a piece of advice in a certain advice class,
 ;; hence, advices can be redefined by defining an advice with the same class
-;; and name. Advice names are global symbols, hence, the same name space
+;; and name.  Advice names are global symbols, hence, the same name space
 ;; conventions used for function names should be applied.
 
 ;; An optional <position> specifies where in the current list of advices of
-;; the specified <class> this new advice will be placed. <position> has to
+;; the specified <class> this new advice will be placed.  <position> has to
 ;; be either `first', `last' or a number that specifies a zero-based
-;; position (`first' is equivalent to 0). If no position is specified
-;; `first' will be used as a default. If this call to `defadvice' redefines
+;; position (`first' is equivalent to 0).  If no position is specified
+;; `first' will be used as a default.  If this call to `defadvice' redefines
 ;; an already existing advice (see above) then the position argument will
 ;; be ignored and the position of the already existing advice will be used.
 
 ;; An optional <arglist> which has to be a list can be used to define the
-;; argument list of the advised function. This argument list should of
+;; argument list of the advised function.  This argument list should of
 ;; course be compatible with the argument list of the original function,
 ;; otherwise functions that call the advised function with the original
-;; argument list in mind will break. If more than one advice specify an
+;; argument list in mind will break.  If more than one advice specify an
 ;; argument list then the first one (the one with the smallest position)
 ;; found in the list of before/around/after advices will be used.
 
@@ -267,10 +245,10 @@
 ;;   `disable': Specifies that the defined advice should be disabled, hence,
 ;;              it will not be used in an activation until somebody enables it.
 ;;   `preactivate': Specifies that the advised function should get preactivated
-;;              at macro-expansion/compile time of this `defadvice'. This
+;;              at macro-expansion/compile time of this `defadvice'.  This
 ;;              generates a compiled advised definition according to the
 ;;              current advice state which will be used during activation
-;;              if appropriate. Only use this if the `defadvice' gets
+;;              if appropriate.  Only use this if the `defadvice' gets
 ;;              actually compiled.
 
 ;; An optional <documentation-string> can be supplied to document the advice.
@@ -278,20 +256,20 @@
 ;; documentation strings of the original function and other advices.
 
 ;; An optional <interactive-form> form can be supplied to change/add
-;; interactive behavior of the original function. If more than one advice
+;; interactive behavior of the original function.  If more than one advice
 ;; has an `(interactive ...)' specification then the first one (the one
 ;; with the smallest position) found in the list of before/around/after
 ;; advices will be used.
 
 ;; A possibly empty list of <body-forms> specifies the body of the advice in
-;; an implicit progn. The body of an advice can access/change arguments,
+;; an implicit progn.  The body of an advice can access/change arguments,
 ;; the return value, the binding environment, and can have all sorts of
 ;; other side effects.
 
 ;; @@ Assembling advised definitions:
 ;; ==================================
 ;; Suppose a function/macro/subr/special-form has N pieces of before advice,
-;; M pieces of around advice and K pieces of after advice. Assuming none of
+;; M pieces of around advice and K pieces of after advice.  Assuming none of
 ;; the advices is protected, its advised definition will look like this
 ;; (body-form indices correspond to the position of the respective advice in
 ;; that advice class):
@@ -330,11 +308,11 @@
 ;; be expanded into a proper documentation string upon call of `documentation'.
 
 ;; (interactive ...) is an optional interactive form either taken from the
-;; original function or from a before/around/after advice. For advised
+;; original function or from a before/around/after advice.  For advised
 ;; interactive subrs that do not have an interactive form specified in any
 ;; advice we have to use (interactive) and then call the subr interactively
 ;; if the advised function was called interactively, because the
-;; interactive specification of subrs is not accessible. This is the only
+;; interactive specification of subrs is not accessible.  This is the only
 ;; case where changing the values of arguments will not have an affect
 ;; because they will be reset by the interactive specification of the subr.
 ;; If this is a problem one can always specify an interactive form in a
@@ -343,45 +321,44 @@
 ;;
 ;; Then the body forms of the various advices in the various classes of advice
 ;; are assembled in order.  The forms of around advice L are normally part of
-;; one of the forms of around advice L-1. An around advice can specify where
+;; one of the forms of around advice L-1.  An around advice can specify where
 ;; the forms of the wrapped or surrounded forms should go with the special
-;; keyword `ad-do-it', which will be substituted with a `progn' containing the
-;; forms of the surrounded code.
+;; keyword `ad-do-it', which will run the forms of the surrounded code.
 
 ;; The innermost part of the around advice onion is
 ;;      <apply original definition to <arglist>>
-;; whose form depends on the type of the original function. The variable
-;; `ad-return-value' will be set to its result. This variable is visible to
+;; whose form depends on the type of the original function.  The variable
+;; `ad-return-value' will be set to its result.  This variable is visible to
 ;; all pieces of advice which can access and modify it before it gets returned.
 ;;
 ;; The semantic structure of advised functions that contain protected pieces
-;; of advice is the same. The only difference is that `unwind-protect' forms
+;; of advice is the same.  The only difference is that `unwind-protect' forms
 ;; make sure that the protected advice gets executed even if some previous
-;; piece of advice had an error or a non-local exit. If any around advice is
+;; piece of advice had an error or a non-local exit.  If any around advice is
 ;; protected then the whole around advice onion will be protected.
 
 ;; @@ Argument access in advised functions:
 ;; ========================================
 ;; As already mentioned, the simplest way to access the arguments of an
-;; advised function in the body of an advice is to refer to them by name. To
-;; do that, the advice programmer needs to know either the names of the
+;; advised function in the body of an advice is to refer to them by name.
+;; To do that, the advice programmer needs to know either the names of the
 ;; argument variables of the original function, or the names used in the
-;; argument list redefinition given in a piece of advice. While this simple
+;; argument list redefinition given in a piece of advice.  While this simple
 ;; method might be sufficient in many cases, it has the disadvantage that it
 ;; is not very portable because it hardcodes the argument names into the
 ;; advice. If the definition of the original function changes the advice
-;; might break even though the code might still be correct. Situations like
+;; might break even though the code might still be correct.  Situations like
 ;; that arise, for example, if one advises a subr like `eval-region' which
 ;; gets redefined in a non-advice style into a function by the edebug
-;; package. If the advice assumes `eval-region' to be a subr it might break
-;; once edebug is loaded. Similar situations arise when one wants to use the
+;; package.  If the advice assumes `eval-region' to be a subr it might break
+;; once edebug is loaded.  Similar situations arise when one wants to use the
 ;; same piece of advice across different versions of Emacs.
 
 ;; As a solution to that advice provides argument list access macros that get
 ;; translated into the proper access forms at activation time, i.e., when the
-;; advised definition gets constructed. Access macros access actual arguments
+;; advised definition gets constructed.  Access macros access actual arguments
 ;; by position regardless of how these actual argument get distributed onto
-;; the argument variables of a function. The rational behind this is that in
+;; the argument variables of a function.  The rational behind this is that in
 ;; Emacs Lisp the semantics of an argument is strictly determined by its
 ;; position (there are no keyword arguments).
 
@@ -393,9 +370,9 @@
 ;;
 ;;    (foo 0 1 2 3 4 5 6)
 
-;; which means that X=0, Y=1, Z=2 and R=(3 4 5 6). The assumption is that
-;; the semantics of an actual argument is determined by its position. It is
-;; this semantics that has to be known by the advice programmer. Then s/he
+;; which means that X=0, Y=1, Z=2 and R=(3 4 5 6).  The assumption is that
+;; the semantics of an actual argument is determined by its position.  It is
+;; this semantics that has to be known by the advice programmer.  Then s/he
 ;; can access these arguments in a piece of advice with some of the
 ;; following macros (the arrows indicate what value they will return):
 
@@ -408,17 +385,17 @@
 
 ;; `(ad-get-arg <position>)' will return the actual argument that was supplied
 ;; at <position>, `(ad-get-args <position>)' will return the list of actual
-;; arguments supplied starting at <position>. Note that these macros can be
+;; arguments supplied starting at <position>.  Note that these macros can be
 ;; used without any knowledge about the form of the actual argument list of
 ;; the original function.
 
 ;; Similarly, `(ad-set-arg <position> <value-form>)' can be used to set the
-;; value of the actual argument at <position> to <value-form>. For example,
+;; value of the actual argument at <position> to <value-form>.  For example,
 ;;
 ;;   (ad-set-arg 5 "five")
 ;;
 ;; will have the effect that R=(3 4 "five" 6) once the original function is
-;; called. `(ad-set-args <position> <value-list-form>)' can be used to set
+;; called.  `(ad-set-args <position> <value-list-form>)' can be used to set
 ;; the list of actual arguments starting at <position> to <value-list-form>.
 ;; For example,
 ;;
@@ -427,7 +404,7 @@
 ;; will have the effect that X=5, Y=4, Z=3 and R=(2 1 0) once the original
 ;; function is called.
 
-;; All these access macros are text macros rather than real Lisp macros. When
+;; All these access macros are text macros rather than real Lisp macros.  When
 ;; the advised definition gets constructed they get replaced with actual access
 ;; forms depending on the argument list of the advised function, i.e., after
 ;; that argument access is in most cases as efficient as using the argument
@@ -437,7 +414,7 @@
 ;; =======================================================
 ;; Some functions (such as `trace-function' defined in trace.el) need a
 ;; method of accessing the names and bindings of the arguments of an
-;; arbitrary advised function. To do that within an advice one can use the
+;; arbitrary advised function.  To do that within an advice one can use the
 ;; special keyword `ad-arg-bindings' which is a text macro that will be
 ;; substituted with a form that will evaluate to a list of binding
 ;; specifications, one for every argument variable.  These binding
@@ -463,7 +440,7 @@
 ;; ==========================
 ;; Because `defadvice' allows the specification of the argument list
 ;; of the advised function we need a mapping mechanism that maps this
-;; argument list onto that of the original function. Hence SYM and
+;; argument list onto that of the original function.  Hence SYM and
 ;; NEWDEF have to be properly mapped onto the &rest variable when the
 ;; original definition is called. Advice automatically takes care of
 ;; that mapping, hence, the advice programmer can specify an argument
@@ -474,11 +451,10 @@
 ;; @@ Activation and deactivation:
 ;; ===============================
 ;; The definition of an advised function does not change until all its advice
-;; gets actually activated. Activation can either happen with the `activate'
+;; gets actually activated.  Activation can either happen with the `activate'
 ;; flag specified in the `defadvice', with an explicit call or interactive
-;; invocation of `ad-activate', or if forward advice is enabled (i.e., the
-;; value of `ad-activate-on-definition' is t) at the time an already advised
-;; function gets defined.
+;; invocation of `ad-activate', or at the time an already advised function
+;; gets defined.
 
 ;; When a function gets first activated its original definition gets saved,
 ;; all defined and enabled pieces of advice will get combined with the
@@ -496,7 +472,7 @@
 ;; the file that contained the `defadvice' with the `preactivate' flag.
 
 ;; `ad-deactivate' can be used to back-define an advised function to its
-;; original definition. It can be called interactively or directly. Because
+;; original definition.  It can be called interactively or directly.  Because
 ;; `ad-activate' caches the advised definition the function can be
 ;; reactivated via `ad-activate' with only minor overhead (it is checked
 ;; whether the current advice state is consistent with the cached
@@ -504,12 +480,12 @@
 
 ;; `ad-activate-regexp' and `ad-deactivate-regexp' can be used to de/activate
 ;; all currently advised function that have a piece of advice with a name that
-;; contains a match for a regular expression. These functions can be used to
+;; contains a match for a regular expression.  These functions can be used to
 ;; de/activate sets of functions depending on certain advice naming
 ;; conventions.
 
 ;; Finally, `ad-activate-all' and `ad-deactivate-all' can be used to
-;; de/activate all currently advised functions. These are useful to
+;; de/activate all currently advised functions.  These are useful to
 ;; (temporarily) return to an un/advised state.
 
 ;; @@@ Reasons for the separation of advice definition and activation:
@@ -521,26 +497,26 @@
 
 ;; The advantage of this is that various pieces of advice can be defined
 ;; before they get combined into an advised definition which avoids
-;; unnecessary constructions of intermediate advised definitions. The more
+;; unnecessary constructions of intermediate advised definitions.  The more
 ;; important advantage is that it allows the implementation of forward advice.
 ;; Advice information for a certain function accumulates as the value of the
-;; `advice-info' property of the function symbol. This accumulation is
+;; `advice-info' property of the function symbol.  This accumulation is
 ;; completely independent of the fact that that function might not yet be
-;; defined. The special forms `defun' and `defmacro' have been advised to
-;; check whether the function/macro they defined had advice information
-;; associated with it. If so and forward advice is enabled, the original
+;; defined.  The macros `defun' and `defmacro' check whether the
+;; function/macro they defined had advice information
+;; associated with it.  If so and forward advice is enabled, the original
 ;; definition will be saved, and then the advice will be activated.
 
 ;; @@ Enabling/disabling pieces or sets of advice:
 ;; ===============================================
 ;; A major motivation for the development of this advice package was to bring
 ;; a little bit more structure into the function overloading chaos in Emacs
-;; Lisp. Many packages achieve some of their functionality by adding a little
+;; Lisp.  Many packages achieve some of their functionality by adding a little
 ;; bit (or a lot) to the standard functionality of some Emacs Lisp function.
-;; ange-ftp is a very popular package that achieves its magic by overloading
-;; most Emacs Lisp functions that deal with files. A popular function that's
-;; overloaded by many packages is `expand-file-name'. The situation that one
-;; function is multiply overloaded can arise easily.
+;; ange-ftp is a very popular package that used to achieve its magic by
+;; overloading most Emacs Lisp functions that deal with files.  A popular
+;; function that's overloaded by many packages is `expand-file-name'.
+;; The situation that one function is multiply overloaded can arise easily.
 
 ;; Once in a while it would be desirable to be able to disable some/all
 ;; overloads of a particular package while keeping all the rest.  Ideally -
@@ -548,7 +524,7 @@
 ;; I know I am dreaming right now... In that ideal case the enable/disable
 ;; mechanism of advice could be used to achieve just that.
 
-;; Every piece of advice is associated with an enablement flag. When the
+;; Every piece of advice is associated with an enablement flag.  When the
 ;; advised definition of a particular function gets constructed (e.g., during
 ;; activation) only the currently enabled pieces of advice will be considered.
 ;; This mechanism allows one to have different "views" of an advised function
@@ -556,17 +532,15 @@
 
 ;; Another motivation for this mechanism is that it allows one to define a
 ;; piece of advice for some function yet keep it dormant until a certain
-;; condition is met. Until then activation of the function will not make use
-;; of that piece of advice. Once the condition is met the advice can be
+;; condition is met.  Until then activation of the function will not make use
+;; of that piece of advice.  Once the condition is met the advice can be
 ;; enabled and a reactivation of the function will add its functionality as
-;; part of the new advised definition. For example, the advices of `defun'
-;; etc. used by advice itself will stay disabled until `ad-start-advice' is
-;; called and some variables have the proper values.  Hence, if somebody
+;; part of the new advised definition.  Hence, if somebody
 ;; else advised these functions too and activates them the advices defined
 ;; by advice will get used only if they are intended to be used.
 
 ;; The main interface to this mechanism are the interactive functions
-;; `ad-enable-advice' and `ad-disable-advice'. For example, the following
+;; `ad-enable-advice' and `ad-disable-advice'.  For example, the following
 ;; would disable a particular advice of the function `foo':
 ;;
 ;;    (ad-disable-advice 'foo 'before 'my-advice)
@@ -576,28 +550,28 @@
 ;;
 ;;    (ad-activate 'foo)
 ;;
-;; or interactively. To disable whole sets of advices one can use a regular
-;; expression mechanism. For example, let us assume that ange-ftp actually
+;; or interactively.  To disable whole sets of advices one can use a regular
+;; expression mechanism.  For example, let us assume that ange-ftp actually
 ;; used advice to overload all its functions, and that it used the
 ;; "ange-ftp-" prefix for all its advice names, then we could temporarily
 ;; disable all its advices with
 ;;
-;;    (ad-disable-regexp "^ange-ftp-")
+;;    (ad-disable-regexp "\\`ange-ftp-")
 ;;
 ;; and the following call would put that actually into effect:
 ;;
-;;    (ad-activate-regexp "^ange-ftp-")
+;;    (ad-activate-regexp "\\`ange-ftp-")
 ;;
 ;; A safer way would have been to use
 ;;
-;;    (ad-update-regexp "^ange-ftp-")
+;;    (ad-update-regexp "\\`ange-ftp-")
 ;;
 ;; instead which would have only reactivated currently actively advised
-;; functions, but not functions that were currently inactive. All these
+;; functions, but not functions that were currently inactive.  All these
 ;; functions can also be called interactively.
 
 ;; A certain piece of advice is considered a match if its name contains a
-;; match for the regular expression. To enable ange-ftp again we would use
+;; match for the regular expression.  To enable ange-ftp again we would use
 ;; `ad-enable-regexp' and then activate or update again.
 
 ;; @@ Forward advice, automatic advice activation:
@@ -616,7 +590,7 @@
 ;; of advice definition and activation that makes it possible to accumulate
 ;; advice information without having the original function already defined,
 ;; 2) special versions of the built-in functions `fset/defalias' which check
-;; for advice information whenever they define a function. If advice
+;; for advice information whenever they define a function.  If advice
 ;; information was found then the advice will immediately get activated when
 ;; the function gets defined.
 
@@ -625,16 +599,11 @@
 ;; file, and the function has some advice-info stored with it then that
 ;; advice will get activated right away.
 
-;; @@@ Enabling automatic advice activation:
-;; =========================================
-;; Automatic advice activation is enabled by default. It can be disabled with
-;; `M-x ad-stop-advice' and enabled again with `M-x ad-start-advice'.
-
 ;; @@ Caching of advised definitions:
 ;; ==================================
 ;; After an advised definition got constructed it gets cached as part of the
 ;; advised function's advice-info so it can be reused, for example, after an
-;; intermediate deactivation. Because the advice-info of a function might
+;; intermediate deactivation.  Because the advice-info of a function might
 ;; change between the time of caching and reuse a cached definition gets
 ;; a cache-id associated with it so it can be verified whether the cached
 ;; definition is still valid (the main application of this is preactivation
@@ -642,19 +611,19 @@
 
 ;; When an advised function gets activated and a verifiable cached definition
 ;; is available, then that definition will be used instead of creating a new
-;; advised definition from scratch. If you want to make sure that a new
+;; advised definition from scratch.  If you want to make sure that a new
 ;; definition gets constructed then you should use `ad-clear-cache' before you
 ;; activate the advised function.
 
 ;; @@ Preactivation:
 ;; =================
-;; Constructing an advised definition is moderately expensive. In a situation
+;; Constructing an advised definition is moderately expensive.  In a situation
 ;; where one package defines a lot of advised functions it might be
 ;; prohibitively expensive to do all the advised definition construction at
-;; runtime. Preactivation is a mechanism that allows compile-time construction
+;; runtime.  Preactivation is a mechanism that allows compile-time construction
 ;; of compiled advised definitions that can be activated cheaply during
-;; runtime. Preactivation uses the caching mechanism to do that. Here's how it
-;; works:
+;; runtime.  Preactivation uses the caching mechanism to do that.  Here's how
+;; it works:
 
 ;; When the byte-compiler compiles a `defadvice' that has the `preactivate'
 ;; flag specified, it uses the current original definition of the advised
@@ -665,27 +634,27 @@
 ;; byte-compiler.
 ;; When the file with the compiled, preactivating `defadvice' gets loaded the
 ;; precompiled advised definition will be cached on the advised function's
-;; advice-info. When it gets activated (can be immediately on execution of the
+;; advice-info.  When it gets activated (can be immediately on execution of the
 ;; `defadvice' or any time later) the cache-id gets checked against the
 ;; current state of advice and if it is verified the precompiled definition
-;; will be used directly (the verification is pretty cheap). If it couldn't get
-;; verified a new advised definition for that function will be built from
-;; scratch, hence, the efficiency added by the preactivation mechanism does
-;; not at all impair the flexibility of the advice mechanism.
+;; will be used directly (the verification is pretty cheap).  If it couldn't
+;; get verified a new advised definition for that function will be built from
+;; scratch, hence, the efficiency added by the preactivation mechanism does not
+;; at all impair the flexibility of the advice mechanism.
 
 ;; MORAL: In order get all the efficiency out of preactivation the advice
 ;;        state of an advised function at the time the file with the
 ;;        preactivating `defadvice' gets byte-compiled should be exactly
 ;;        the same as it will be when the advice of that function gets
-;;        actually activated. If it is not there is a high chance that the
+;;        actually activated.  If it is not there is a high chance that the
 ;;        cache-id will not match and hence a new advised definition will
 ;;        have to be constructed at runtime.
 
-;; Preactivation and forward advice do not contradict each other. It is
+;; Preactivation and forward advice do not contradict each other.  It is
 ;; perfectly ok to load a file with a preactivating `defadvice' before the
-;; original definition of the advised function is available. The constructed
+;; original definition of the advised function is available.  The constructed
 ;; advised definition will be used once the original function gets defined and
-;; its advice gets activated. The only constraint is that at the time the
+;; its advice gets activated.  The only constraint is that at the time the
 ;; file with the preactivating `defadvice' got compiled the original function
 ;; definition was available.
 
@@ -697,18 +666,18 @@
 ;;       - `byte-compile' is part of the `features' variable even though you
 ;;         did not use the byte-compiler
 ;;       Right now advice does not provide an elegant way to find out whether
-;;       and why a preactivation failed. What you can do is to trace the
+;;       and why a preactivation failed.  What you can do is to trace the
 ;;       function `ad-cache-id-verification-code' (with the function
 ;;       `trace-function-background' defined in my trace.el package) before
-;;       any of your advised functions get activated. After they got
+;;       any of your advised functions get activated.  After they got
 ;;       activated check whether all calls to `ad-cache-id-verification-code'
-;;       returned `verified' as a result. Other values indicate why the
+;;       returned `verified' as a result.  Other values indicate why the
 ;;       verification failed which should give you enough information to
 ;;       fix your preactivation/compile/load/activation sequence.
 
 ;; IMPORTANT: There is one case (that I am aware of) that can make
 ;; preactivation fail, i.e., a preconstructed advised definition that does
-;; NOT match the current state of advice gets used nevertheless. That case
+;; NOT match the current state of advice gets used nevertheless.  That case
 ;; arises if one package defines a certain piece of advice which gets used
 ;; during preactivation, and another package incompatibly redefines that
 ;; very advice (i.e., same function/class/name), and it is the second advice
@@ -720,30 +689,20 @@
 ;; MORAL-II: Redefining somebody else's advice is BAAAAD (to speak with
 ;; George Walker Bush), and why would you redefine your own advice anyway?
 ;; Advice is a mechanism to facilitate function redefinition, not advice
-;; redefinition (wait until I write Meta-Advice :-). If you really have
-;; to undo somebody else's advice try to write a "neutralizing" advice.
+;; redefinition (wait until I write Meta-Advice :-).  If you really have
+;; to undo somebody else's advice, try to write a "neutralizing" advice.
 
-;; @@ Advising macros and special forms and other dangerous things:
-;; ================================================================
+;; @@ Advising macros and other dangerous things:
+;; ==============================================
 ;; Look at the corresponding tutorial sections for more information on
-;; these topics. Here it suffices to point out that the special treatment
-;; of macros and special forms by the byte-compiler can lead to problems
-;; when they get advised. Macros can create problems because they get
-;; expanded at compile time, hence, they might not have all the necessary
-;; runtime support and such advice cannot be de/activated or changed as
-;; it is possible for functions. Special forms create problems because they
-;; have to be advised "into" macros, i.e., an advised special form is a
-;; implemented as a macro, hence, in most cases the byte-compiler will
-;; not recognize it as a special form anymore which can lead to very strange
-;; results.
-;;
-;; MORAL: - Only advise macros or special forms when you are absolutely sure
-;;          what you are doing.
-;;        - As a safety measure, always do `ad-deactivate-all' before you
-;;          byte-compile a file to make sure that even if some inconsiderate
-;;          person advised some special forms you'll get proper compilation
-;;          results. After compilation do `ad-activate-all' to get back to
-;;          the previous state.
+;; these topics.  Here it suffices to point out that the special treatment
+;; of macros can lead to problems when they get advised.  Macros can create
+;; problems because they get expanded at compile or load time, hence, they
+;; might not have all the necessary runtime support and such advice cannot be
+;; de/activated or changed as it is possible for functions.
+;; Special forms cannot be advised.
+;;
+;; MORAL: - Only advise macros when you are absolutely sure what you are doing.
 
 ;; @@ Adding a piece of advice with `ad-add-advice':
 ;; =================================================
@@ -754,10 +713,10 @@
 ;; @@ Activation/deactivation advices, file load hooks:
 ;; ====================================================
 ;; There are two special classes of advice called `activation' and
-;; `deactivation'. The body forms of these advices are not included into the
+;; `deactivation'.  The body forms of these advices are not included into the
 ;; advised definition of a function, rather they are assembled into a hook
 ;; form which will be evaluated whenever the advice-info of the advised
-;; function gets activated or deactivated. One application of this mechanism
+;; function gets activated or deactivated.  One application of this mechanism
 ;; is to define file load hooks for files that do not provide such hooks.
 ;; For example, suppose you want to print a message whenever `file-x' gets
 ;; loaded, and suppose the last function defined in `file-x' is
@@ -769,7 +728,7 @@
 ;;
 ;; This will constitute a forward advice for function `file-x-last-fn' which
 ;; will get activated when `file-x' is loaded (only if forward advice is
-;; enabled of course). Because there are no "real" pieces of advice
+;; enabled of course).  Because there are no "real" pieces of advice
 ;; available for it, its definition will not be changed, but the activation
 ;; advice will be run during its activation which is equivalent to having a
 ;; file load hook for `file-x'.
@@ -784,14 +743,14 @@
 ;;     enabled advices are considered during construction of an advised
 ;;     definition.
 ;; - Activation:
-;;     Redefine an advised function with its advised definition. Constructs
+;;     Redefine an advised function with its advised definition.  Constructs
 ;;     an advised definition from scratch if no verifiable cached advised
 ;;     definition is available and caches it.
 ;; - Deactivation:
 ;;     Back-define an advised function to its original definition.
 ;; - Update:
 ;;     Reactivate an advised function but only if its advice is currently
-;;     active. This can be used to bring all currently advised function up
+;;     active.  This can be used to bring all currently advised function up
 ;;     to date with the current state of advice without also activating
 ;;     currently inactive functions.
 ;; - Caching:
@@ -800,7 +759,7 @@
 ;; - Preactivation:
 ;;     Is the construction of an advised definition according to the current
 ;;     state of advice during byte-compilation of a file with a preactivating
-;;     `defadvice'. That advised definition can then rather cheaply be used
+;;     `defadvice'.  That advised definition can then rather cheaply be used
 ;;     during activation without having to construct an advised definition
 ;;     from scratch at runtime.
 
@@ -860,12 +819,8 @@
 
 ;; @ Foo games: An advice tutorial
 ;; ===============================
-;; The following tutorial was created in Emacs 18.59. Left-justified
+;; The following tutorial was created in Emacs 18.59.  Left-justified
 ;; s-expressions are input forms followed by one or more result forms.
-;; First we have to start the advice magic:
-;;
-;; (ad-start-advice)
-;; nil
 ;;
 ;; We start by defining an innocent looking function `foo' that simply
 ;; adds 1 to its argument X:
@@ -988,19 +943,6 @@
 ;; (call-interactively 'foo)
 ;; 6
 ;;
-;; Let's have a look at what the definition of `foo' looks like now
-;; (indentation added by hand for legibility):
-;;
-;; (symbol-function 'foo)
-;; (lambda (x)
-;;   "$ad-doc: foo$"
-;;   (interactive (list 5))
-;;   (let (ad-return-value)
-;;     (setq x (1- x))
-;;     (setq x (1+ x))
-;;     (setq ad-return-value (ad-Orig-foo x))
-;;     ad-return-value))
-;;
 ;; @@ Around advices:
 ;; ==================
 ;; Now we'll try some `around' advices. An around advice is a wrapper around
@@ -1038,20 +980,6 @@
 ;; (foo 3)
 ;; 8
 ;;
-;; Again, let's see what the definition of `foo' looks like so far:
-;;
-;; (symbol-function 'foo)
-;; (lambda (x)
-;;   "$ad-doc: foo$"
-;;   (interactive (list 5))
-;;   (let (ad-return-value)
-;;     (setq x (1- x))
-;;     (setq x (1+ x))
-;;     (let ((x (* x 2)))
-;;       (let ((x (1+ x)))
-;;         (setq ad-return-value (ad-Orig-foo x))))
-;;     ad-return-value))
-;;
 ;; @@ Controlling advice activation:
 ;; =================================
 ;; In every `defadvice' so far we have used the flag `activate' to activate
@@ -1071,9 +999,9 @@
 ;; 8
 ;;
 ;; Now we define another advice and activate which will also activate the
-;; previous advice `fg-times-x'. Note the use of the special variable
+;; previous advice `fg-times-x'.  Note the use of the special variable
 ;; `ad-return-value' in the body of the advice which is set to the result of
-;; the original function. If we change its value then the value returned by
+;; the original function.  If we change its value then the value returned by
 ;; the advised function will be changed accordingly:
 ;;
 ;; (defadvice foo (after fg-times-x-again act)
@@ -1121,24 +1049,6 @@
 ;; "Let's clean up now!"
 ;; error-in-foo
 ;;
-;; Again, let's see what `foo' looks like:
-;;
-;; (symbol-function 'foo)
-;; (lambda (x)
-;;   "$ad-doc: foo$"
-;;   (interactive (list 5))
-;;   (let (ad-return-value)
-;;     (unwind-protect
-;;         (progn (setq x (1- x))
-;;                (setq x (1+ x))
-;;                (let ((x (* x 2)))
-;;                  (let ((x (1+ x)))
-;;                    (setq ad-return-value (ad-Orig-foo x))))
-;;                (setq ad-return-value (* ad-return-value x))
-;;                (setq ad-return-value (* ad-return-value x)))
-;;       (print "Let's clean up now!"))
-;;     ad-return-value))
-;;
 ;; @@ Compilation of advised definitions:
 ;; ======================================
 ;; Finally, we can specify the `compile' keyword in a `defadvice' to say
@@ -1150,13 +1060,10 @@
 ;;   (print "Let's clean up now!"))
 ;; foo
 ;;
-;; Now `foo' is byte-compiled:
+;; Now `foo's advice is byte-compiled:
 ;;
-;; (symbol-function 'foo)
-;; (lambda (x)
-;;   "$ad-doc: foo$"
-;;   (interactive (byte-code "....." [5] 1))
-;;   (byte-code "....." [ad-return-value x nil ((byte-code "....." [print "Let's clean up now!"] 2)) * 2 ad-Orig-foo] 6))
+;; (byte-code-function-p 'ad-Advice-foo)
+;; t
 ;;
 ;; (foo 3)
 ;; "Let's clean up now!"
@@ -1262,7 +1169,7 @@
 ;; deactivate functions that have a piece of advice defined by a certain
 ;; package (we save the old definition to check out caching):
 ;;
-;; (setq old-definition (symbol-function 'foo))
+;; (setq old-definition (symbol-function 'ad-Advice-foo))
 ;; (lambda (x) ....)
 ;;
 ;; (ad-deactivate-regexp "^fg-")
@@ -1274,7 +1181,7 @@
 ;; (ad-activate-regexp "^fg-")
 ;; nil
 ;;
-;; (eq old-definition (symbol-function 'foo))
+;; (eq old-definition (symbol-function 'ad-Advice-foo))
 ;; t
 ;;
 ;; (foo 3)
@@ -1283,14 +1190,6 @@
 ;;
 ;; @@ Forward advice:
 ;; ==================
-;; To enable automatic activation of forward advice we first have to set
-;; `ad-activate-on-definition' to t and restart advice:
-;;
-;; (setq ad-activate-on-definition t)
-;; t
-;;
-;; (ad-start-advice)
-;; (ad-activate-defined-function)
 ;;
 ;; Let's define a piece of advice for an undefined function:
 ;;
@@ -1303,9 +1202,7 @@
 ;; (fboundp 'bar)
 ;; nil
 ;;
-;; Now we define it and the forward advice will get activated (only because
-;; `ad-activate-on-definition' was t when we started advice above with
-;; `ad-start-advice'):
+;; Now we define it and the forward advice will get activated:
 ;;
 ;; (defun bar (x)
 ;;   "Subtract 1 from X."
@@ -1357,7 +1254,7 @@
 ;; (ad-activate 'fie)
 ;; fie
 ;;
-;; (eq cached-definition (symbol-function 'fie))
+;; (eq cached-definition (symbol-function 'ad-Advice-fie))
 ;; t
 ;;
 ;; (fie 2)
@@ -1365,7 +1262,7 @@
 ;;
 ;; If you put a preactivating `defadvice' into a Lisp file that gets byte-
 ;; compiled then the constructed advised definition will get compiled by
-;; the byte-compiler. For that to occur in a v18 Emacs you had to put the
+;; the byte-compiler.  For that to occur in a v18 Emacs you had to put the
 ;; `defadvice' inside a `defun' because the v18 compiler did not compile
 ;; top-level forms other than `defun' or `defmacro', for example,
 ;;
@@ -1407,18 +1304,16 @@
 ;; constructed during preactivation was used, even though we did not specify
 ;; the `compile' flag:
 ;;
-;; (symbol-function 'fum)
-;; (lambda (x)
-;;   "$ad-doc: fum$"
-;;   (byte-code "....." [ad-return-value x nil * 2 ad-Orig-fum] 4))
+;; (byte-code-function-p 'ad-Advice-fum)
+;; t
 ;;
 ;; (fum 2)
 ;; 8
 ;;
 ;; A preactivated definition will only be used if it matches the current
-;; function definition and advice information. If it does not match it
+;; function definition and advice information.  If it does not match it
 ;; will simply be discarded and a new advised definition will be constructed
-;; from scratch. For example, let's first remove all advice-info for `fum':
+;; from scratch.  For example, let's first remove all advice-info for `fum':
 ;;
 ;; (ad-unadvise 'fum)
 ;; (("fie") ("bar") ("foo") ...)
@@ -1431,7 +1326,7 @@
 ;; fum
 ;;
 ;; When we now try to use a preactivation it will not be used because the
-;; current advice state is different from the one at preactivation time. This
+;; current advice state is different from the one at preactivation time.  This
 ;; is no tragedy, everything will work as expected just not as efficient,
 ;; because a new advised definition has to be constructed from scratch:
 ;;
@@ -1440,7 +1335,7 @@
 ;;
 ;; A new uncompiled advised definition got constructed:
 ;;
-;; (ad-compiled-p (symbol-function 'fum))
+;; (byte-code-function-p 'ad-Advice-fum)
 ;; nil
 ;;
 ;; (fum 2)
@@ -1448,7 +1343,7 @@
 ;;
 ;; MORAL: To get all the efficiency out of preactivation the function
 ;; definition and advice state at preactivation time must be the same as the
-;; state at activation time. Preactivation does work with forward advice, all
+;; state at activation time.  Preactivation does work with forward advice, all
 ;; that's necessary is that the definition of the forward advised function is
 ;; available when the `defadvice' with the preactivation gets compiled.
 ;;
@@ -1702,15 +1597,9 @@
 ;; @@ Compilation idiosyncrasies:
 ;; ==============================
 
-;; `defadvice' expansion needs quite a few advice functions and variables,
-;; hence, I need to preload the file before it can be compiled.  To avoid
-;; interference of bogus compiled files I always preload the source file:
-(provide 'advice-preload)
-;; During a normal load this is a noop:
-(require 'advice-preload "advice.el")
 (require 'macroexp)
 ;; At run-time also, since ad-do-advised-functions returns code that uses it.
-(require 'cl-lib)
+(eval-when-compile (require 'cl-lib))
 
 ;; @@ Variable definitions:
 ;; ========================
@@ -1789,7 +1678,7 @@ generates a copy of TREE."
 ;;       (after  adv1 adv2 ...)
 ;;       (activation  adv1 adv2 ...)
 ;;       (deactivation  adv1 adv2 ...)
-;;       (origname . <symbol fbound to origdef>)
+;;       (advicefunname . <symbol fbound to assembled advice function>)
 ;;       (cache . (<advised-definition> . <id>)))
 
 ;; List of currently advised though not necessarily activated functions
@@ -1816,7 +1705,7 @@ generates a copy of TREE."
 On each iteration VAR will be bound to the name of an advised function
 \(a symbol)."
   (declare (indent 1))
-  `(cl-dolist (,(car varform) ad-advised-functions)
+  `(dolist (,(car varform) ad-advised-functions)
      (setq ,(car varform) (intern (car ,(car varform))))
      ,@body))
 
@@ -1882,18 +1771,17 @@ either t or nil, and DEFINITION should be a list of the form
 
 ;; ad-find-advice uses the alist structure directly ->
 ;; change if this data structure changes!!
-(defmacro ad-advice-name (advice)
-  (list 'car advice))
-(defmacro ad-advice-protected (advice)
-  (list 'nth 1 advice))
-(defmacro ad-advice-enabled (advice)
-  (list 'nth 2 advice))
-(defmacro ad-advice-definition (advice)
-  (list 'nth 3 advice))
+(defsubst ad-advice-name (advice) (car advice))
+(defsubst ad-advice-protected (advice) (nth 1 advice))
+(defsubst ad-advice-enabled (advice) (nth 2 advice))
+(defsubst ad-advice-definition (advice) (nth 3 advice))
 
 (defun ad-advice-set-enabled (advice flag)
   (rplaca (cdr (cdr advice)) flag))
 
+(defvar ad-advice-classes '(before around after activation deactivation)
+  "List of defined advice classes.")
+
 (defun ad-class-p (thing)
   (memq thing ad-advice-classes))
 (defun ad-name-p (thing)
@@ -1906,9 +1794,6 @@ either t or nil, and DEFINITION should be a list of the form
 ;; @@ Advice access functions:
 ;; ===========================
 
-;; List of defined advice classes:
-(defvar ad-advice-classes '(before around after activation deactivation))
-
 (defun ad-has-enabled-advice (function class)
   "True if at least one of FUNCTION's advices in CLASS is enabled."
   (cl-dolist (advice (ad-get-advice-info-field function class))
@@ -1948,58 +1833,23 @@ Redefining advices affect the construction of an advised definition."
 ;; Whether advised definitions created by automatic activations will be
 ;; compiled depends on the value of `ad-default-compilation-action'.
 
-;; Since calling `ad-activate-internal' in the built-in definition of `fset' can
-;; create major disasters we have to be a bit careful. One precaution is
-;; to provide a dummy definition for `ad-activate-internal' which can be used to
-;; turn off automatic advice activation (e.g., when `ad-stop-advice' or
-;; `ad-recover-normality' are called). Another is to avoid recursive calls
-;; to `ad-activate' by using `ad-with-auto-activation-disabled' where
-;; appropriate, especially in a safe version of `fset'.
-
-(defun ad--defalias-fset (fsetfun function definition)
-  (funcall (or fsetfun #'fset) function definition)
-  (ad-activate-internal function nil))
-
-;; For now define `ad-activate-internal' to the dummy definition:
-(defun ad-activate-internal (_function &optional _compile)
-  "Automatic advice activation is disabled. `ad-start-advice' enables it."
-  nil)
-
-;; This is just a copy of the above:
-(defun ad-activate-internal-off (_function &optional _compile)
-  "Automatic advice activation is disabled. `ad-start-advice' enables it."
-  nil)
-
-;; This will be t for top-level calls to `ad-activate-internal-on':
-(defvar ad-activate-on-top-level t)
-
-(defmacro ad-with-auto-activation-disabled (&rest body)
-  `(let ((ad-activate-on-top-level nil))
-    ,@body))
-
-;; @@ Access functions for original definitions:
-;; ============================================
-;; The advice-info of an advised function contains its `origname' which is
-;; a symbol that is fbound to the original definition available at the first
-;; proper activation of the function after a valid re/definition.  If the
-;; original was defined via fcell indirection then `origname' will be defined
-;; just so.  Hence, to get hold of the actual original definition of a function
-;; we need to use `ad-real-orig-definition'.
-
-(defun ad-make-origname (function)
-  "Make name to be used to call the original FUNCTION."
-  (intern (format "ad-Orig-%s" function)))
+(defalias 'ad-activate-internal 'ad-activate)
 
-(defmacro ad-get-orig-definition (function)
-  `(let ((origname (ad-get-advice-info-field ,function 'origname)))
-    (if (fboundp origname)
-        (symbol-function origname))))
+(defun ad-make-advicefunname (function)
+  "Make name to be used to call the assembled advice function."
+  (intern (format "ad-Advice-%s" function)))
 
-(defmacro ad-set-orig-definition (function definition)
-  `(fset (ad-get-advice-info-field ,function 'origname) ,definition))
+(defun ad-get-orig-definition (function) ;FIXME: Rename to "-unadvised-".
+  (if (symbolp function)
+      (setq function (if (fboundp function)
+                         (advice--strip-macro (symbol-function function)))))
+  (while (advice--p function) (setq function (advice--cdr function)))
+  function)
 
-(defmacro ad-clear-orig-definition (function)
-  `(fmakunbound (ad-get-advice-info-field ,function 'origname)))
+(defun ad-clear-advicefunname-definition (function)
+  (let ((advicefunname (ad-get-advice-info-field function 'advicefunname)))
+    (advice-remove function advicefunname)
+    (fmakunbound advicefunname)))
 
 
 ;; @@ Interactive input functions:
@@ -2259,7 +2109,7 @@ See Info node `(elisp)Computed Advice' for detailed documentation."
   (cond ((not (ad-is-advised function))
          (ad-initialize-advice-info function)
          (ad-set-advice-info-field
-          function 'origname (ad-make-origname function))))
+          function 'advicefunname (ad-make-advicefunname function))))
   (let* ((previous-position
           (ad-advice-position function class (ad-advice-name advice)))
          (advices (ad-get-advice-info-field function class))
@@ -2374,7 +2224,8 @@ the name of the advised function from the docstring.  This is needed
 to generate a proper advised docstring even if we are just given a
 definition (see the code for `documentation')."
   (eval-when-compile
-    (propertize "Advice doc string" 'dynamic-docstring-function
+    (propertize "Advice function assembled by advice.el."
+                'dynamic-docstring-function
                 #'ad--make-advised-docstring)))
 
 (defun ad-advised-definition-p (definition)
@@ -2388,16 +2239,15 @@ definition (see the code for `documentation')."
 
 (defun ad-definition-type (definition)
   "Return symbol that describes the type of DEFINITION."
+  ;; These symbols are only ever used to check a cache entry's validity.
+  ;; The suffix `2' reflects the fact that we're using version 2 of advice
+  ;; representations, so cache entries preactivated with version
+  ;; 1 can't be used.
   (cond
-   ((ad-macro-p definition) 'macro)
-   ((ad-subr-p definition)
-    (if (special-form-p definition)
-        'special-form
-      'subr))
-   ((or (ad-lambda-p definition)
-        (ad-compiled-p definition))
-    'function)
-   ((ad-advice-p definition) 'advice)))
+   ((ad-macro-p definition) 'macro2)
+   ((ad-subr-p definition) 'subr2)
+   ((or (ad-lambda-p definition) (ad-compiled-p definition)) 'fun2)
+   ((ad-advice-p definition) 'advice2))) ;; FIXME: Can this ever happen?
 
 (defun ad-has-proper-definition (function)
   "True if FUNCTION is a symbol with a proper definition.
@@ -2417,9 +2267,9 @@ For that it has to be fbound with a non-autoload definition."
           definition))))
 
 (defun ad-real-orig-definition (function)
-  "Find FUNCTION's real original definition starting from its `origname'."
-  (if (ad-is-advised function)
-      (ad-real-definition (ad-get-advice-info-field function 'origname))))
+  (let* ((fun1 (ad-get-orig-definition function))
+         (fun2 (indirect-function fun1)))
+    (unless (autoloadp fun2) fun2)))
 
 (defun ad-is-compilable (function)
   "True if FUNCTION has an interpreted definition that can be compiled."
@@ -2430,24 +2280,15 @@ For that it has to be fbound with a non-autoload definition."
 
 (defvar warning-suppress-types)         ;From warnings.el.
 (defun ad-compile-function (function)
-  "Byte-compiles FUNCTION (or macro) if it is not yet compiled."
-  (interactive "aByte-compile function: ")
-  (if (ad-is-compilable function)
-      ;; Need to turn off auto-activation
-      ;; because `byte-compile' uses `fset':
-      (ad-with-auto-activation-disabled
-       (require 'bytecomp)
-       (require 'warnings)              ;To define warning-suppress-types
-                                        ;before we let-bind it.
-       (let ((symbol (make-symbol "advice-compilation"))
-             (byte-compile-warnings byte-compile-warnings)
-             ;; Don't pop up windows showing byte-compiler warnings.
-             (warning-suppress-types '((bytecomp))))
-         (if (featurep 'cl)
-             (byte-compile-disable-warning 'cl-functions))
-         (fset symbol (symbol-function function))
-         (byte-compile symbol)
-         (fset function (symbol-function symbol))))))
+  "Byte-compile the assembled advice function."
+  (require 'bytecomp)
+  (require 'warnings)  ;To define warning-suppress-types before we let-bind it.
+  (let ((byte-compile-warnings byte-compile-warnings)
+        ;; Don't pop up windows showing byte-compiler warnings.
+        (warning-suppress-types '((bytecomp))))
+    (if (featurep 'cl)
+        (byte-compile-disable-warning 'cl-functions))
+    (byte-compile (ad-get-advice-info-field function 'advicefunname))))
 
 ;; @@@ Accessing argument lists:
 ;; =============================
@@ -2634,7 +2475,7 @@ Excess source arguments will be neglected, missing source arguments will be
 supplied as nil.  Returns a `funcall' or `apply' form with the second element
 being `function' which has to be replaced by an actual function argument.
 Example: `(ad-map-arglists '(a &rest args) '(w x y z))' will return
-         `(funcall function a (car args) (car (cdr args)) (nth 2 args))'."
+         `(funcall ad--addoit-function a (car args) (car (cdr args)) (nth 2 args))'."
   (let* ((parsed-source-arglist (ad-parse-arglist source-arglist))
          (source-reqopt-args (append (nth 0 parsed-source-arglist)
                                      (nth 1 parsed-source-arglist)))
@@ -2648,7 +2489,7 @@ Example: `(ad-map-arglists '(a &rest args) '(w x y z))' will return
     ;; This produces ``error-proof'' target function calls with the exception
     ;; of a case like (&rest a) mapped onto (x &rest y) where the actual args
     ;; supplied to A might not be enough to supply the required target arg X
-    (append (list (if need-apply 'apply 'funcall) 'function)
+    (append (list (if need-apply 'apply 'funcall) 'ad--addoit-function)
             (cond (need-apply
                    ;; `apply' can take care of that directly:
                    (append source-reqopt-args (list source-rest-arg)))
@@ -2663,13 +2504,6 @@ Example: `(ad-map-arglists '(a &rest args) '(w x y z))' will return
                                           (nthcdr (length target-reqopt-args)
                                                   source-reqopt-args)))))))))
 
-(defun ad-make-mapped-call (source-arglist target-arglist target-function)
-  "Make form to call TARGET-FUNCTION with args from SOURCE-ARGLIST."
-  (let ((mapped-form (ad-map-arglists source-arglist target-arglist)))
-    (if (eq (car mapped-form) 'funcall)
-        (cons target-function (cdr (cdr mapped-form)))
-      (prog1 mapped-form
-        (setcar (cdr mapped-form) (list 'quote target-function))))))
 
 ;; @@@ Making an advised documentation string:
 ;; ===========================================
@@ -2697,13 +2531,6 @@ Example: `(ad-map-arglists '(a &rest args) '(w x y z))' will return
 
 (require 'help-fns)         ;For help-split-fundoc and help-add-fundoc-usage.
 
-(defun ad-make-advised-docstring (function &optional style)
-  (let* ((origdef (ad-real-orig-definition function))
-         (origdoc
-          ;; Retrieve raw doc, key substitution will be taken care of later:
-          (documentation origdef t)))
-    (ad--make-advised-docstring origdoc function style)))
-
 (defun ad--make-advised-docstring (origdoc function &optional style)
   "Construct a documentation string for the advised FUNCTION.
 It concatenates the original documentation with the documentation
@@ -2712,14 +2539,14 @@ according to STYLE.  STYLE can be `plain', everything else
 will be interpreted as `default'.  The order of the advice documentation
 strings corresponds to before/around/after and the individual ordering
 in any of these classes."
-  (let* ((origdef (ad-real-orig-definition function))
-         (origtype (symbol-name (ad-definition-type origdef)))
-         (usage (help-split-fundoc origdoc function))
+  (if (and (symbolp function)
+           (string-match "\\`ad-+Advice-" (symbol-name function)))
+      (setq function
+            (intern (substring (symbol-name function) (match-end 0)))))
+  (let* ((usage (help-split-fundoc origdoc function))
          paragraphs advice-docstring)
     (setq usage (if (null usage) t (setq origdoc (cdr usage)) (car usage)))
     (if origdoc (setq paragraphs (list origdoc)))
-    (unless (eq style 'plain)
-      (push (concat "This " origtype " is advised.") paragraphs))
     (dolist (class ad-advice-classes)
       (dolist (advice (ad-get-enabled-advices function class))
         (setq advice-docstring
@@ -2735,8 +2562,6 @@ in any of these classes."
                        #'ad--make-advised-docstring)))
     (help-add-fundoc-usage origdoc usage)))
 
-(defun ad-make-plain-docstring (function)
-  (ad-make-advised-docstring function 'plain))
 
 ;; @@@ Accessing overriding arglists and interactive forms:
 ;; ========================================================
@@ -2770,64 +2595,18 @@ in any of these classes."
   (if (and (ad-is-advised function)
            (ad-has-redefining-advice function))
       (let* ((origdef (ad-real-orig-definition function))
-             (origname (ad-get-advice-info-field function 'origname))
-             (orig-interactive-p (commandp origdef))
-             (orig-subr-p (ad-subr-p origdef))
-             (orig-special-form-p (special-form-p origdef))
-             (orig-macro-p (ad-macro-p origdef))
              ;; Construct the individual pieces that we need for assembly:
-             (orig-arglist (ad-arglist origdef))
+             (orig-arglist (let ((args (ad-arglist origdef)))
+                             ;; The arglist may still be unknown.
+                             (if (listp args) args '(&rest args))))
              (advised-arglist (or (ad-advised-arglist function)
                                   orig-arglist))
-             (advised-interactive-form (ad-advised-interactive-form function))
-             (interactive-form
-              (cond (orig-macro-p nil)
-                    (advised-interactive-form)
-                    ((interactive-form origdef)
-                     (interactive-form
-                      (if (and (symbolp function) (get function 'elp-info))
-                          (aref (get function 'elp-info) 2)
-                        origdef)))))
+             (interactive-form (ad-advised-interactive-form function))
              (orig-form
-              (cond ((or orig-special-form-p orig-macro-p)
-                     ;; Special forms and macros will be advised into macros.
-                     ;; The trick is to construct an expansion for the advised
-                     ;; macro that does the correct thing when it gets eval'ed.
-                     ;; For macros we'll just use the expansion of the original
-                     ;; macro and return that. This way compiled advised macros
-                     ;; will be expanded into something useful. Note that after
-                     ;; advices have full control over whether they want to
-                     ;; evaluate the expansion (the value of `ad-return-value')
-                     ;; at macro expansion time or not. For special forms there
-                     ;; is no solution that interacts reasonably with the
-                     ;; compiler, hence we just evaluate the original at macro
-                     ;; expansion time and return the result. The moral of that
-                     ;; is that one should always deactivate advised special
-                     ;; forms before one byte-compiles a file.
-                     `(,(if orig-macro-p 'macroexpand 'eval)
-                       (cons ',origname
-                             ,(ad-get-arguments advised-arglist 0))))
-                    ((and orig-subr-p
-                          orig-interactive-p
-                          (not interactive-form)
-                          (not advised-interactive-form))
-                     ;; Check whether we were called interactively
-                     ;; in order to do proper prompting:
-                     `(if (called-interactively-p 'any)
-                          (call-interactively ',origname)
-                        ,(ad-make-mapped-call advised-arglist
-                                              orig-arglist
-                                              origname)))
-                    ;; And now for normal functions and non-interactive subrs
-                    ;; (or subrs whose interactive behavior was advised):
-                    (t (ad-make-mapped-call
-                        advised-arglist orig-arglist origname)))))
+              (ad-map-arglists advised-arglist orig-arglist)))
 
         ;; Finally, build the sucker:
         (ad-assemble-advised-definition
-         (cond (orig-macro-p 'macro)
-               (orig-special-form-p 'special-form)
-               (t 'function))
          advised-arglist
          (ad-make-advised-definition-docstring function)
          interactive-form
@@ -2837,13 +2616,11 @@ in any of these classes."
          (ad-get-enabled-advices function 'after)))))
 
 (defun ad-assemble-advised-definition
-    (type args docstring interactive orig &optional befores arounds afters)
-
-  "Assembles an original and its advices into an advised function.
-It constructs a function or macro definition according to TYPE which has to
-be either `macro', `function' or `special-form'.  ARGS is the argument list
-that has to be used, DOCSTRING if non-nil defines the documentation of the
-definition, INTERACTIVE if non-nil is the interactive form to be used,
+    (args docstring interactive orig &optional befores arounds afters)
+  "Assemble the advices into an overall advice function.
+ARGS is the argument list that has to be used,
+DOCSTRING if non-nil defines the documentation of the definition,
+INTERACTIVE if non-nil is the interactive form to be used,
 ORIG is a form that calls the body of the original unadvised function,
 and BEFORES, AROUNDS and AFTERS are the lists of advices with which ORIG
 should be modified.  The assembled function will be returned."
@@ -2894,16 +2671,12 @@ should be modified.  The assembled function will be returned."
                              (ad-body-forms (ad-advice-definition advice)))))))
 
     (setq definition
-          `(,@(if (memq type '(macro special-form)) '(macro))
-            lambda
-            ,args
+          `(lambda (ad--addoit-function ,@args)
             ,@(if docstring (list docstring))
             ,@(if interactive (list interactive))
             (let (ad-return-value)
               ,@after-forms
-              ,(if (eq type 'special-form)
-                   '(list 'quote ad-return-value)
-                   'ad-return-value))))
+              ad-return-value)))
 
     (ad-insert-argument-access-forms definition args)))
 
@@ -3000,11 +2773,11 @@ advised definition from scratch."
   "Generate an identifying image of the current advices of FUNCTION."
   (let ((original-definition (ad-real-orig-definition function))
         (cached-definition (ad-get-cache-definition function)))
-    (list (mapcar (function (lambda (advice) (ad-advice-name advice)))
+    (list (mapcar #'ad-advice-name
                   (ad-get-enabled-advices function 'before))
-          (mapcar (function (lambda (advice) (ad-advice-name advice)))
+          (mapcar #'ad-advice-name
                   (ad-get-enabled-advices function 'around))
-          (mapcar (function (lambda (advice) (ad-advice-name advice)))
+          (mapcar #'ad-advice-name
                   (ad-get-enabled-advices function 'after))
           (ad-definition-type original-definition)
           (if (equal (ad-arglist original-definition)
@@ -3147,25 +2920,32 @@ The resulting FUNCTION will be compiled if `ad-should-compile' returns t.
 The current definition and its cache-id will be put into the cache."
   (let ((verified-cached-definition
          (if (ad-verify-cache-id function)
-             (ad-get-cache-definition function))))
-    (fset function
-                  (or verified-cached-definition
-                      (ad-make-advised-definition function)))
+             (ad-get-cache-definition function)))
+        (advicefunname (ad-get-advice-info-field function 'advicefunname)))
+    (fset advicefunname
+          (or verified-cached-definition
+              (ad-make-advised-definition function)))
+    (advice-add function :around advicefunname)
     (if (ad-should-compile function compile)
-        (ad-compile-function function))
+        (byte-compile advicefunname))
     (if verified-cached-definition
-        (if (not (eq verified-cached-definition (symbol-function function)))
+        (if (not (eq verified-cached-definition
+                     (symbol-function advicefunname)))
             ;; we must have compiled, cache the compiled definition:
-            (ad-set-cache
-             function (symbol-function function) (ad-get-cache-id function)))
+            (ad-set-cache function (symbol-function advicefunname)
+                          (ad-get-cache-id function)))
       ;; We created a new advised definition, cache it with a proper id:
       (ad-clear-cache function)
       ;; ad-make-cache-id needs the new cached definition:
-      (ad-set-cache function (symbol-function function) nil)
+      (ad-set-cache function (symbol-function advicefunname) nil)
       (ad-set-cache
-       function (symbol-function function) (ad-make-cache-id function)))))
+       function (symbol-function advicefunname) (ad-make-cache-id function)))))
 
-(defun ad-handle-definition (function)
+(defun ad--defalias-fset (fsetfun function newdef)
+  ;; Besides ad-redefinition-action we use this defalias-fset-function hook
+  ;; for two other reasons:
+  ;; - for `activation/deactivation' advices.
+  ;; - to rebuild the ad-Advice-* function with the right argument names.
   "Handle re/definition of an advised FUNCTION during de/activation.
 If FUNCTION does not have an original definition associated with it and
 the current definition is usable, then it will be stored as FUNCTION's
@@ -3177,33 +2957,27 @@ associated with it but got redefined with a new definition and then
 de/activated.  If you do not like the current redefinition action change
 the value of `ad-redefinition-action' and de/activate again."
   (let ((original-definition (ad-get-orig-definition function))
-        (current-definition (if (ad-real-definition function)
-                                (symbol-function function))))
+        (current-definition (ad-get-orig-definition newdef)))
     (if original-definition
         (if current-definition
-            (if (and (not (eq current-definition original-definition))
-                     ;; Redefinition with an advised definition from a
-                     ;; different function won't count as such:
-                     (not (ad-advised-definition-p current-definition)))
-                ;; we have a redefinition:
+            (if (not (eq current-definition original-definition))
+                ;; We have a redefinition:
                 (if (not (memq ad-redefinition-action '(accept discard warn)))
-                    (error "ad-handle-definition (see its doc): `%s' %s"
+                    (error "ad-redefinition-action: `%s' %s"
                            function "invalidly redefined")
                   (if (eq ad-redefinition-action 'discard)
-                      (fset function original-definition)
-                    (ad-set-orig-definition function current-definition)
+                      nil ;; Just drop it!
+                    (funcall (or fsetfun #'fset) function newdef)
+                    (ad-activate-internal function)
                     (if (eq ad-redefinition-action 'warn)
                         (message "ad-handle-definition: `%s' got redefined"
                                  function))))
               ;; either advised def or correct original is in place:
               nil)
-          ;; we have an undefinition, ignore it:
-          nil)
-      (if current-definition
-          ;; we have a first definition, save it as original:
-          (ad-set-orig-definition function current-definition)
-        ;; we don't have anything noteworthy:
-        nil))))
+          ;; We have an undefinition, ignore it:
+          (funcall (or fsetfun #'fset) function newdef))
+      (funcall (or fsetfun #'fset) function newdef)
+      (when current-definition (ad-activate-internal function)))))
 
 
 ;; @@ The top-level advice interface:
@@ -3229,24 +3003,20 @@ definition will always be cached for later usage."
   (interactive
    (list (ad-read-advised-function "Activate advice of")
          current-prefix-arg))
-  (if ad-activate-on-top-level
-      ;; avoid recursive calls to `ad-activate':
-      (ad-with-auto-activation-disabled
-        (if (not (ad-is-advised function))
-            (error "ad-activate: `%s' is not advised" function)
-          (ad-handle-definition function)
-          ;; Just return for forward advised and not yet defined functions:
-          (if (ad-get-orig-definition function)
-              (if (not (ad-has-any-advice function))
-                  (ad-unadvise function)
-                ;; Otherwise activate the advice:
-                (cond ((ad-has-redefining-advice function)
-                       (ad-activate-advised-definition function compile)
-                       (ad-set-advice-info-field function 'active t)
-                       (eval (ad-make-hook-form function 'activation))
-                       function)
-                      ;; Here we are if we have all disabled advices:
-                      (t (ad-deactivate function)))))))))
+  (if (not (ad-is-advised function))
+      (error "ad-activate: `%s' is not advised" function)
+    ;; Just return for forward advised and not yet defined functions:
+    (if (ad-get-orig-definition function)
+        (if (not (ad-has-any-advice function))
+            (ad-unadvise function)
+          ;; Otherwise activate the advice:
+          (cond ((ad-has-redefining-advice function)
+                 (ad-activate-advised-definition function compile)
+                 (ad-set-advice-info-field function 'active t)
+                 (eval (ad-make-hook-form function 'activation))
+                 function)
+                ;; Here we are if we have all disabled advices:
+                (t (ad-deactivate function)))))))
 
 (defalias 'ad-activate-on 'ad-activate)
 
@@ -3261,11 +3031,10 @@ a call to `ad-activate'."
   (if (not (ad-is-advised function))
       (error "ad-deactivate: `%s' is not advised" function)
     (cond ((ad-is-active function)
-           (ad-handle-definition function)
            (if (not (ad-get-orig-definition function))
                (error "ad-deactivate: `%s' has no original definition"
                       function)
-             (fset function (ad-get-orig-definition function))
+             (ad-clear-advicefunname-definition function)
              (ad-set-advice-info-field function 'active nil)
              (eval (ad-make-hook-form function 'deactivation))
              function)))))
@@ -3287,7 +3056,7 @@ If FUNCTION was not advised this will be a noop."
   (cond ((ad-is-advised function)
          (if (ad-is-active function)
              (ad-deactivate function))
-         (ad-clear-orig-definition function)
+         (ad-clear-advicefunname-definition function)
          (ad-set-advice-info function nil)
          (ad-pop-advised-function function))))
 
@@ -3302,9 +3071,7 @@ Use in emergencies."
    (list (intern
           (completing-read "Recover advised function: " obarray nil t))))
   (cond ((ad-is-advised function)
-         (cond ((ad-get-orig-definition function)
-                (fset function (ad-get-orig-definition function))
-                (ad-clear-orig-definition function)))
+         (ad-clear-advicefunname-definition function)
          (ad-set-advice-info function nil)
          (ad-pop-advised-function function))))
 
@@ -3544,35 +3311,15 @@ undone on exit of this macro."
 ;; @@ Starting, stopping and recovering from the advice package magic:
 ;; ===================================================================
 
-(defun ad-start-advice ()
-  "Start the automatic advice handling magic."
-  (interactive)
-  ;; Advising `ad-activate-internal' means death!!
-  (ad-set-advice-info 'ad-activate-internal nil)
-  (fset 'ad-activate-internal 'ad-activate))
-
-(defun ad-stop-advice ()
-  "Stop the automatic advice handling magic.
-You should only need this in case of Advice-related emergencies."
-  (interactive)
-  ;; Advising `ad-activate-internal' means death!!
-  (ad-set-advice-info 'ad-activate-internal nil)
-  (fset 'ad-activate-internal 'ad-activate-internal-off))
-
 (defun ad-recover-normality ()
   "Undo all advice related redefinitions and unadvises everything.
 Use only in REAL emergencies."
   (interactive)
-  ;; Advising `ad-activate-internal' means death!!
-  (ad-set-advice-info 'ad-activate-internal nil)
-  (fset 'ad-activate-internal 'ad-activate-internal-off)
   (ad-recover-all)
   (ad-do-advised-functions (function)
     (message "Oops! Left over advised function %S" function)
     (ad-pop-advised-function function)))
 
-(ad-start-advice)
-
 (provide 'advice)
 
 ;;; advice.el ends here
diff --git a/lisp/emacs-lisp/checkdoc.el b/lisp/emacs-lisp/checkdoc.el
index ffa42e97221..1cbed17cbab 100644
--- a/lisp/emacs-lisp/checkdoc.el
+++ b/lisp/emacs-lisp/checkdoc.el
@@ -124,7 +124,7 @@
 ;; Adding your own checks:
 ;;
 ;;   You can experiment with adding your own checks by setting the
-;; hooks `checkdoc-style-functions' and `checkdoc-comment-style-hooks'.
+;; hooks `checkdoc-style-functions' and `checkdoc-comment-style-functions'.
 ;; Return a string which is the error you wish to report.  The cursor
 ;; position should be preserved.
 ;;
diff --git a/lisp/emacs-lisp/cl-lib.el b/lisp/emacs-lisp/cl-lib.el
index a9be08b1383..bfc63134985 100644
--- a/lisp/emacs-lisp/cl-lib.el
+++ b/lisp/emacs-lisp/cl-lib.el
@@ -3,7 +3,7 @@
 ;; Copyright (C) 1993, 2001-2012  Free Software Foundation, Inc.
 
 ;; Author: Dave Gillespie <daveg@synaptics.com>
-;; Version: 2.02
+;; Version: 1.0
 ;; Keywords: extensions
 
 ;; This file is part of GNU Emacs.
diff --git a/lisp/emacs-lisp/cl-loaddefs.el b/lisp/emacs-lisp/cl-loaddefs.el
index eb58d17c02e..69882e36f22 100644
--- a/lisp/emacs-lisp/cl-loaddefs.el
+++ b/lisp/emacs-lisp/cl-loaddefs.el
@@ -267,7 +267,7 @@ including `cl-block' and `cl-eval-when'.
 ;;;;;;  cl-typecase cl-ecase cl-case cl-load-time-value cl-eval-when
 ;;;;;;  cl-destructuring-bind cl-function cl-defmacro cl-defun cl-gentemp
 ;;;;;;  cl-gensym cl--compiler-macro-cXXr cl--compiler-macro-list*)
-;;;;;;  "cl-macs" "cl-macs.el" "c7ad09a74a1d2969406e7e2aaf3812fc")
+;;;;;;  "cl-macs" "cl-macs.el" "a7d9b56ea588b869813de8ed7ec1fbcd")
 ;;; Generated autoloads from cl-macs.el
 
 (autoload 'cl--compiler-macro-list* "cl-macs" "\
@@ -416,7 +416,7 @@ This is compatible with Common Lisp, but note that `defun' and
 (put 'cl-return-from 'lisp-indent-function '1)
 
 (autoload 'cl-loop "cl-macs" "\
-The Common Lisp `cl-loop' macro.
+The Common Lisp `loop' macro.
 Valid clauses are:
   for VAR from/upfrom/downfrom NUM to/upto/downto/above/below NUM by NUM,
   for VAR in LIST by FUNC, for VAR on LIST by FUNC, for VAR = INIT then EXPR,
@@ -432,14 +432,14 @@ Valid clauses are:
 \(fn CLAUSE...)" nil t)
 
 (autoload 'cl-do "cl-macs" "\
-The Common Lisp `cl-do' loop.
+The Common Lisp `do' loop.
 
 \(fn ((VAR INIT [STEP])...) (END-TEST [RESULT...]) BODY...)" nil t)
 
 (put 'cl-do 'lisp-indent-function '2)
 
 (autoload 'cl-do* "cl-macs" "\
-The Common Lisp `cl-do*' loop.
+The Common Lisp `do*' loop.
 
 \(fn ((VAR INIT [STEP])...) (END-TEST [RESULT...]) BODY...)" nil t)
 
@@ -501,7 +501,7 @@ a `let' form, except that the list of symbols can be computed at run-time.
 (put 'cl-progv 'lisp-indent-function '2)
 
 (autoload 'cl-flet "cl-macs" "\
-Make temporary function definitions.
+Make local function definitions.
 Like `cl-labels' but the definitions are not recursive.
 
 \(fn ((FUNC ARGLIST BODY...) ...) FORM...)" nil t)
@@ -509,7 +509,7 @@ Like `cl-labels' but the definitions are not recursive.
 (put 'cl-flet 'lisp-indent-function '1)
 
 (autoload 'cl-flet* "cl-macs" "\
-Make temporary function definitions.
+Make local function definitions.
 Like `cl-flet' but the definitions can refer to previous ones.
 
 \(fn ((FUNC ARGLIST BODY...) ...) FORM...)" nil t)
diff --git a/lisp/emacs-lisp/cl-macs.el b/lisp/emacs-lisp/cl-macs.el
index 3c46c40242d..918e992512c 100644
--- a/lisp/emacs-lisp/cl-macs.el
+++ b/lisp/emacs-lisp/cl-macs.el
@@ -260,9 +260,11 @@ The name is made by appending a number to PREFIX, default \"G\"."
                         (require 'help-fns)
                         (cons (help-add-fundoc-usage
                                (if (stringp (car hdr)) (pop hdr))
-                               (format "%S"
-                                       (cons 'fn
-                                             (cl--make-usage-args orig-args))))
+                               ;; Be careful with make-symbol and (back)quote,
+                               ;; see bug#12884.
+                               (let ((print-gensym nil) (print-quoted t))
+                                 (format "%S" (cons 'fn (cl--make-usage-args
+                                                         orig-args)))))
                               hdr)))
                     (list `(let* ,cl--bind-lets
                              ,@(nreverse cl--bind-forms)
@@ -756,7 +758,7 @@ This is compatible with Common Lisp, but note that `defun' and
 
 ;;;###autoload
 (defmacro cl-loop (&rest loop-args)
-  "The Common Lisp `cl-loop' macro.
+  "The Common Lisp `loop' macro.
 Valid clauses are:
   for VAR from/upfrom/downfrom NUM to/upto/downto/above/below NUM by NUM,
   for VAR in LIST by FUNC, for VAR on LIST by FUNC, for VAR = INIT then EXPR,
@@ -1501,7 +1503,7 @@ such that COMBO is equivalent to (and . CLAUSES)."
 
 ;;;###autoload
 (defmacro cl-do (steps endtest &rest body)
-  "The Common Lisp `cl-do' loop.
+  "The Common Lisp `do' loop.
 
 \(fn ((VAR INIT [STEP])...) (END-TEST [RESULT...]) BODY...)"
   (declare (indent 2)
@@ -1513,7 +1515,7 @@ such that COMBO is equivalent to (and . CLAUSES)."
 
 ;;;###autoload
 (defmacro cl-do* (steps endtest &rest body)
-  "The Common Lisp `cl-do*' loop.
+  "The Common Lisp `do*' loop.
 
 \(fn ((VAR INIT [STEP])...) (END-TEST [RESULT...]) BODY...)"
   (declare (indent 2) (debug cl-do))
@@ -1648,7 +1650,7 @@ a `let' form, except that the list of symbols can be computed at run-time."
 
 ;;;###autoload
 (defmacro cl-flet (bindings &rest body)
-  "Make temporary function definitions.
+  "Make local function definitions.
 Like `cl-labels' but the definitions are not recursive.
 
 \(fn ((FUNC ARGLIST BODY...) ...) FORM...)"
@@ -1672,7 +1674,7 @@ Like `cl-labels' but the definitions are not recursive.
 
 ;;;###autoload
 (defmacro cl-flet* (bindings &rest body)
-  "Make temporary function definitions.
+  "Make local function definitions.
 Like `cl-flet' but the definitions can refer to previous ones.
 
 \(fn ((FUNC ARGLIST BODY...) ...) FORM...)"
diff --git a/lisp/emacs-lisp/eieio-datadebug.el b/lisp/emacs-lisp/eieio-datadebug.el
index ec470d21bf3..a1db1972b83 100644
--- a/lisp/emacs-lisp/eieio-datadebug.el
+++ b/lisp/emacs-lisp/eieio-datadebug.el
@@ -131,7 +131,7 @@ PREBUTTONTEXT is some text between PREFIX and the object button."
 (defun eieio-debug-methodinvoke (method class)
   "Show the method invocation order for METHOD with CLASS object."
   (interactive "aMethod: \nXClass Expression: ")
-  (let* ((eieio-pre-method-execution-hooks
+  (let* ((eieio-pre-method-execution-functions
           (lambda (l) (throw 'moose l) ))
          (data
           (catch 'moose (eieio-generic-call
diff --git a/lisp/emacs-lisp/gv.el b/lisp/emacs-lisp/gv.el
index 02eec08f96b..5488330a1a4 100644
--- a/lisp/emacs-lisp/gv.el
+++ b/lisp/emacs-lisp/gv.el
@@ -236,7 +236,7 @@ For example, (setf (cadr x) y) is equivalent to (setcar (cdr x) y).
 The return value is the last VAL in the list.
 
 \(fn PLACE VAL PLACE VAL ...)"
-  (declare (debug (gv-place form)))
+  (declare (debug (&rest [gv-place form])))
   (if (and args (null (cddr args)))
       (let ((place (pop args))
             (val (car args)))
diff --git a/lisp/emacs-lisp/nadvice.el b/lisp/emacs-lisp/nadvice.el
index ca1ebf3cad2..540e0166ec2 100644
--- a/lisp/emacs-lisp/nadvice.el
+++ b/lisp/emacs-lisp/nadvice.el
@@ -30,7 +30,7 @@
 ;;   holds a function.
 ;;   This part provides mainly 2 macros: `add-function' and `remove-function'.
 ;;
-;; - The second part provides `add-advice' and `remove-advice' which are
+;; - The second part provides `advice-add' and `advice-remove' which are
 ;;   refined version of the previous macros specially tailored for the case
 ;;   where the place that we want to modify is a `symbol-function'.
 
@@ -109,18 +109,33 @@ Each element has the form (WHERE BYTECODE STACK) where:
   (propertize "Advised function"
               'dynamic-docstring-function #'advice--make-docstring)) ;; )
 
+(defun advice-eval-interactive-spec (spec)
+  "Evaluate the interactive spec SPEC."
+  (cond
+   ((stringp spec)
+    ;; There's no direct access to the C code (in call-interactively) that
+    ;; processes those specs, but that shouldn't stop us, should it?
+    ;; FIXME: Despite appearances, this is not faithful: SPEC and
+    ;; (advice-eval-interactive-spec SPEC) will behave subtly differently w.r.t
+    ;; command-history (and maybe a few other details).
+    (call-interactively `(lambda (&rest args) (interactive ,spec) args)))
+   ;; ((functionp spec) (funcall spec))
+   (t (eval spec))))
+
 (defun advice--make-interactive-form (function main)
-  ;; TODO: Make it possible to do around-like advising on the
-  ;; interactive forms (bug#12844).
   ;; TODO: make it so that interactive spec can be a constant which
   ;; dynamically checks the advice--car/cdr to do its job.
-  ;; TODO: Implement interactive-read-args:
-  ;;(when (or (commandp function) (commandp main))
-  ;;  `(interactive-read-args
-  ;;    (cadr (or (interactive-form function) (interactive-form main)))))
-  ;; FIXME: This loads autoloaded functions too eagerly.
+  ;; For that, advice-eval-interactive-spec needs to be more faithful.
+  ;; FIXME: The calls to interactive-form below load autoloaded functions
+  ;; too eagerly.
+  (let ((fspec (cadr (interactive-form function))))
+    (when (eq 'function (car-safe fspec)) ;; Macroexpanded lambda?
+      (setq fspec (nth 1 fspec)))
+    (if (functionp fspec)
+        `(funcall ',fspec
+                  ',(cadr (interactive-form main)))
   (cadr (or (interactive-form function)
-            (interactive-form main))))
+                (interactive-form main))))))
 
 (defsubst advice--make-1 (byte-code stack-depth function main props)
   "Build a function value that adds FUNCTION to MAIN."
@@ -167,17 +182,31 @@ WHERE is a symbol to select an entry in `advice--where-alist'."
             (advice--make-1 (aref flist 1) (aref flist 3)
                             first nrest props)))))))
 
+(defvar advice--buffer-local-function-sample nil)
+
+(defun advice--set-buffer-local (var val)
+  (if (function-equal val advice--buffer-local-function-sample)
+      (kill-local-variable var)
+    (set (make-local-variable var) val)))
+
+;;;###autoload
+(defun advice--buffer-local (var)
+  "Buffer-local value of VAR, presumed to contain a function."
+  (declare (gv-setter advice--set-buffer-local))
+  (if (local-variable-p var) (symbol-value var)
+    (setq advice--buffer-local-function-sample
+          (lambda (&rest args) (apply (default-value var) args)))))
+
 ;;;###autoload
 (defmacro add-function (where place function &optional props)
   ;; TODO:
-  ;; - provide something like `around' for interactive forms.
-  ;; - provide some kind of buffer-local functionality at least when `place'
-  ;;   is a variable.
   ;; - obsolete with-wrapper-hook (mostly requires buffer-local support).
   ;; - provide some kind of control over ordering.  E.g. debug-on-entry, ELP
   ;;   and tracing want to stay first.
-  ;; - maybe also let `where' specify some kind of predicate and use it
+  ;; - maybe let `where' specify some kind of predicate and use it
   ;;   to implement things like mode-local or eieio-defmethod.
+  ;;   Of course, that only makes sense if the predicates of all advices can
+  ;;   be combined and made more efficient.
   ;; :before is like a normal add-hook on a normal hook.
   ;; :before-while is like add-hook on run-hook-with-args-until-failure.
   ;; :before-until is like add-hook on run-hook-with-args-until-success.
@@ -197,8 +226,24 @@ call OLDFUN here:
 If FUNCTION was already added, do nothing.
 PROPS is an alist of additional properties, among which the following have
 a special meaning:
-- `name': a string or symbol.  It can be used to refer to this piece of advice."
+- `name': a string or symbol.  It can be used to refer to this piece of advice.
+
+PLACE cannot be a simple variable.  Instead it should either be
+\(default-value 'VAR) or (local 'VAR) depending on whether FUNCTION
+should be applied to VAR buffer-locally or globally.
+
+If one of FUNCTION or OLDFUN is interactive, then the resulting function
+is also interactive.  There are 3 cases:
+- FUNCTION is not interactive: the interactive spec of OLDFUN is used.
+- The interactive spec of FUNCTION is itself a function: it should take one
+  argument (the interactive spec of OLDFUN, which it can pass to
+  `advice-eval-interactive-spec') and return the list of arguments to use.
+- Else, use the interactive spec of FUNCTION and ignore the one of OLDFUN."
   (declare (debug t)) ;;(indent 2)
+  (cond ((eq 'local (car-safe place))
+         (setq place `(advice--buffer-local ,@(cdr place))))
+        ((symbolp place)
+         (error "Use (default-value '%S) or (local '%S)" place place)))
   `(advice--add-function ,where (gv-ref ,place) ,function ,props))
 
 ;;;###autoload
@@ -213,6 +258,10 @@ If FUNCTION was not added to PLACE, do nothing.
 Instead of FUNCTION being the actual function, it can also be the `name'
 of the piece of advice."
   (declare (debug t))
+  (cond ((eq 'local (car-safe place))
+         (setq place `(advice--buffer-local ,@(cdr place))))
+        ((symbolp place)
+         (error "Use (default-value '%S) or (local '%S)" place place)))
   (gv-letplace (getter setter) place
     (macroexp-let2 nil new `(advice--remove-function ,getter ,function)
       `(unless (eq ,new ,getter) ,(funcall setter new)))))
@@ -234,7 +283,7 @@ of the piece of advice."
   (cond
    ((special-form-p def)
     ;; Not worth the trouble trying to handle this, I think.
-    (error "add-advice failure: %S is a special form" symbol))
+    (error "advice-add failure: %S is a special form" symbol))
    ((and (symbolp def)
          (eq 'macro (car-safe (ignore-errors (indirect-function def)))))
     (let ((newval (cons 'macro (cdr (indirect-function def)))))
@@ -285,28 +334,21 @@ is defined as a macro, alias, command, ..."
   ;; - change all defadvice in lisp/**/*.el.
   ;; - rewrite advice.el on top of this.
   ;; - obsolete advice.el.
-  ;; To make advice.el and nadvice.el interoperate properly I see 2 different
-  ;; ways:
-  ;; - keep them separate: complete the defalias-fset-function setter with
-  ;;   a matching accessor which both nadvice.el and advice.el will have to use
-  ;;   in place of symbol-function.  This can probably be made to work, but
-  ;;   they have to agree on a "protocol".
-  ;; - layer advice.el on top of nadvice.el.  I prefer this approach.  the
-  ;;   simplest way is to make advice.el build one ad-Advice-foo function for
-  ;;   each advised function which is advice-added/removed whenever ad-activate
-  ;;   ad-deactivate is called.
   (let* ((f (and (fboundp symbol) (symbol-function symbol)))
          (nf (advice--normalize symbol f)))
     (unless (eq f nf) ;; Most importantly, if nf == nil!
       (fset symbol nf))
     (add-function where (cond
                          ((eq (car-safe nf) 'macro) (cdr nf))
-                         ;; If the function is not yet defined, we can't yet
-                         ;; install the advice.
-                         ;; FIXME: If it's an autoloaded command, we also
-                         ;; have a problem because we need to load the
-                         ;; command to build the interactive-form.
-                         ((or (not nf) (and (autoloadp nf))) ;; (commandp nf)
+                         ;; Reasons to delay installation of the advice:
+                         ;; - If the function is not yet defined, installing
+                         ;;   the advice would affect `fboundp'ness.
+                         ;; - If it's an autoloaded command,
+                         ;;   advice--make-interactive-form would end up
+                         ;;   loading the command eagerly.
+                         ;; - `autoload' does nothing if the function is
+                         ;;   not an autoload or undefined.
+                         ((or (not nf) (autoloadp nf))
                           (get symbol 'advice--pending))
                          (t (symbol-function symbol)))
                   function props)
diff --git a/lisp/erc/ChangeLog b/lisp/erc/ChangeLog
index 13dbba769a4..e0a88461dc9 100644
--- a/lisp/erc/ChangeLog
+++ b/lisp/erc/ChangeLog
@@ -1,3 +1,7 @@
+2012-11-16  Glenn Morris  <rgm@gnu.org>
+
+        * erc.el (erc-modules): Add "notifications".  Tweak "hecomplete" doc.
+
 2012-10-28  Stefan Monnier  <monnier@iro.umontreal.ca>
 
         * erc-backend.el: Only require `erc' during compilation (bug#12740).
diff --git a/lisp/erc/erc.el b/lisp/erc/erc.el
index 2e97131b603..7cb6fbb595b 100644
--- a/lisp/erc/erc.el
+++ b/lisp/erc/erc.el
@@ -1843,7 +1843,7 @@ removed from the list will be disabled."
            capab-identify)
     (const :tag "completion: Complete nicknames and commands (programmable)"
            completion)
-    (const :tag "hecomplete: Complete nicknames and commands (old)" hecomplete)
+    (const :tag "hecomplete: Complete nicknames and commands (obsolete, use \"completion\")" hecomplete)
     (const :tag "dcc: Provide Direct Client-to-Client support" dcc)
     (const :tag "fill: Wrap long lines" fill)
     (const :tag "identd: Launch an identd server on port 8113" identd)
@@ -1863,6 +1863,8 @@ removed from the list will be disabled."
     (const :tag
            "notify: Notify when the online status of certain users changes"
            notify)
+    (const :tag "notifications: Send notifications on PRIVMSG or nickname mentions"
+           notifications)
     (const :tag "page: Process CTCP PAGE requests from IRC" page)
     (const :tag "readonly: Make displayed lines read-only" readonly)
     (const :tag "replace: Replace text in messages" replace)
diff --git a/lisp/eshell/em-cmpl.el b/lisp/eshell/em-cmpl.el
index a67861e83a9..aa8aae2d245 100644
--- a/lisp/eshell/em-cmpl.el
+++ b/lisp/eshell/em-cmpl.el
@@ -295,8 +295,8 @@ to writing a completion function."
     'pcomplete-expand-and-complete)
   (define-key eshell-command-map [space] 'pcomplete-expand)
   (define-key eshell-command-map [? ] 'pcomplete-expand)
-  (define-key eshell-mode-map [tab] 'pcomplete)
-  (define-key eshell-mode-map [(control ?i)] 'pcomplete)
+  (define-key eshell-mode-map [tab] 'eshell-pcomplete)
+  (define-key eshell-mode-map [(control ?i)] 'eshell-pcomplete)
   ;; jww (1999-10-19): Will this work on anything but X?
   (if (featurep 'xemacs)
       (define-key eshell-mode-map [iso-left-tab] 'pcomplete-reverse)
@@ -449,6 +449,13 @@ to writing a completion function."
                         (all-completions filename obarray 'functionp))
                    completions)))))))
 
+(defun eshell-pcomplete ()
+  "Eshell wrapper for `pcomplete'."
+  (interactive)
+  (if eshell-cmpl-ignore-case
+      (pcomplete-expand-and-complete)  ; hack workaround for bug#12838
+    (pcomplete)))
+
 (provide 'em-cmpl)
 
 ;; Local Variables:
diff --git a/lisp/eshell/em-unix.el b/lisp/eshell/em-unix.el
index d3ddab8af1b..32744c702a6 100644
--- a/lisp/eshell/em-unix.el
+++ b/lisp/eshell/em-unix.el
@@ -306,12 +306,13 @@ Remove (unlink) the FILE(s).")
   (eshell-eval-using-options
    "mkdir" args
    '((?h "help" nil nil "show this usage screen")
+     (?p "parents" nil em-parents "make parent directories as needed")
      :external "mkdir"
      :show-usage
      :usage "[OPTION] DIRECTORY...
 Create the DIRECTORY(ies), if they do not already exist.")
    (while args
-     (eshell-funcalln 'make-directory (car args))
+     (eshell-funcalln 'make-directory (car args) em-parents)
      (setq args (cdr args)))
    nil))
 
diff --git a/lisp/faces.el b/lisp/faces.el
index f5ef88d08b0..9e0ca962499 100644
--- a/lisp/faces.el
+++ b/lisp/faces.el
@@ -487,16 +487,21 @@ with the `default' face (which is always completely specified)."
 (defalias 'face-background-pixmap 'face-stipple)
 
 
+;; FIXME all of these -p functions ignore inheritance (cf face-stipple).
+;; Ie, a face that inherits from an underlined face but does not
+;; specify :underline will return nil.
+;; So these functions don't actually tell you anything about how the
+;; face will _appear_.  So not very useful IMO.
 (defun face-underline-p (face &optional frame)
- "Return non-nil if FACE is underlined.
+ "Return non-nil if FACE specifies a non-nil underlining.
 If the optional argument FRAME is given, report on face FACE in that frame.
 If FRAME is t, report on the defaults for face FACE (for new frames).
 If FRAME is omitted or nil, use the selected frame."
- (eq (face-attribute face :underline frame) t))
+ (face-attribute-specified-or (face-attribute face :underline frame) nil))
 
 
 (defun face-inverse-video-p (face &optional frame)
- "Return non-nil if FACE is in inverse video on FRAME.
+ "Return non-nil if FACE specifies a non-nil inverse-video.
 If the optional argument FRAME is given, report on face FACE in that frame.
 If FRAME is t, report on the defaults for face FACE (for new frames).
 If FRAME is omitted or nil, use the selected frame."
@@ -837,21 +842,24 @@ and DATA is a string, containing the raw bits of the bitmap."
   (set-face-attribute face frame :stipple (or stipple 'unspecified)))
 
 
-(defun set-face-underline-p (face underline &optional frame)
+(defun set-face-underline (face underline &optional frame)
   "Specify whether face FACE is underlined.
 UNDERLINE nil means FACE explicitly doesn't underline.
-UNDERLINE non-nil means FACE explicitly does underlining
-with the same of the foreground color.
-If UNDERLINE is a string, underline with the color named UNDERLINE.
+UNDERLINE t means FACE underlines with its foreground color.
+If UNDERLINE is a string, underline with that color.
+
+UNDERLINE may also be a list of the form (:color COLOR :style STYLE),
+where COLOR is a string or `foreground-color', and STYLE is either
+`line' or `wave'.  :color may be omitted, which means to use the
+foreground color.  :style may be omitted, which means to use a line.
+
 FRAME nil or not specified means change face on all frames.
 Use `set-face-attribute' to ``unspecify'' underlining."
-  (interactive
-   (let ((list (read-face-and-attribute :underline)))
-     (list (car list) (eq (car (cdr list)) t))))
+  (interactive (read-face-and-attribute :underline))
   (set-face-attribute face frame :underline underline))
 
-(define-obsolete-function-alias 'set-face-underline
-                                'set-face-underline-p "22.1")
+(define-obsolete-function-alias 'set-face-underline-p
+                                'set-face-underline "24.3")
 
 
 (defun set-face-inverse-video-p (face inverse-video-p &optional frame)
@@ -866,6 +874,9 @@ Use `set-face-attribute' to ``unspecify'' the inverse video attribute."
   (set-face-attribute face frame :inverse-video inverse-video-p))
 
 
+;; The -p suffix is a hostage to fortune.  What if we want to extend
+;; this to allow more than boolean options?  Exactly this happened
+;; to set-face-underline-p.
 (defun set-face-bold-p (face bold-p &optional frame)
   "Specify whether face FACE is bold.
 BOLD-P non-nil means FACE should explicitly display bold.
@@ -1114,6 +1125,9 @@ name of the attribute for prompting.  Value is the new attribute value."
            (string-to-number new-value)))))
 
 
+;; FIXME this does allow you to enter the list forms of :box,
+;; :stipple, or :underline, because face-valid-attribute-values does
+;; not return those forms.
 (defun read-face-attribute (face attribute &optional frame)
   "Interactively read a new value for FACE's ATTRIBUTE.
 Optional argument FRAME nil or unspecified means read an attribute value
@@ -1125,12 +1139,11 @@ of a global face.  Value is the new attribute value."
     ;; Represent complex attribute values as strings by printing them
     ;; out.  Stipple can be a vector; (WIDTH HEIGHT DATA).  Box can be
     ;; a list `(:width WIDTH :color COLOR)' or `(:width WIDTH :shadow
-    ;; SHADOW)'.
-    (when (and (or (eq attribute :stipple)
-                   (eq attribute :box))
-               (or (consp old-value)
-                   (vectorp old-value)))
-      (setq old-value (prin1-to-string old-value)))
+    ;; SHADOW)'.  Underline can be `(:color COLOR :style STYLE)'.
+    (and (memq attribute '(:box :stipple :underline))
+         (or (consp old-value)
+             (vectorp old-value))
+         (setq old-value (prin1-to-string old-value)))
     (cond ((listp valid)
            (let ((default
                    (or (car (rassoc old-value valid))
@@ -1160,11 +1173,10 @@ of a global face.  Value is the new attribute value."
     ;; Convert stipple and box value text we read back to a list or
     ;; vector if it looks like one.  This makes the assumption that a
     ;; pixmap file name won't start with an open-paren.
-    (when (and (or (eq attribute :stipple)
-                   (eq attribute :box))
-               (stringp new-value)
-               (string-match "^[[(]" new-value))
-      (setq new-value (read new-value)))
+    (and (memq attribute '(:stipple :box :underline))
+         (stringp new-value)
+         (string-match "^[[(]" new-value)
+         (setq new-value (read new-value)))
     new-value))
 
 (declare-function fontset-list "fontset.c" ())
diff --git a/lisp/filecache.el b/lisp/filecache.el
index 2dd7c2673bf..23246c24c45 100644
--- a/lisp/filecache.el
+++ b/lisp/filecache.el
@@ -310,23 +310,22 @@ files in each directory, not to the directory list itself."
 (defun file-cache-add-file (file)
   "Add FILE to the file cache."
   (interactive "fAdd File: ")
-  (if (not (file-exists-p file))
-      (message "Filecache: file %s does not exist" file)
-    (let* ((file-name (file-name-nondirectory file))
-           (dir-name  (file-name-directory    file))
-           (the-entry (assoc-string
-                       file-name file-cache-alist
-                       file-cache-ignore-case)))
-      ;; Does the entry exist already?
-      (if the-entry
-          (if (or (and (stringp (cdr the-entry))
-                       (string= dir-name (cdr the-entry)))
-                  (and (listp (cdr the-entry))
-                       (member dir-name (cdr the-entry))))
-              nil
-            (setcdr the-entry (cons dir-name (cdr the-entry))))
-        ;; If not, add it to the cache
-        (push (list file-name dir-name) file-cache-alist)))))
+  (setq file (file-truename file))
+  (unless (file-exists-p file)
+    (error "Filecache: file %s does not exist" file))
+  (let* ((file-name (file-name-nondirectory file))
+         (dir-name  (file-name-directory file))
+         (the-entry (assoc-string file-name file-cache-alist
+                                  file-cache-ignore-case)))
+    ;; Does the entry exist already?
+    (if the-entry
+        (unless (or (and (stringp (cdr the-entry))
+                         (string= dir-name (cdr the-entry)))
+                    (and (listp (cdr the-entry))
+                         (member dir-name (cdr the-entry))))
+          (setcdr the-entry (cons dir-name (cdr the-entry))))
+      ;; If not, add it to the cache
+      (push (list file-name dir-name) file-cache-alist))))
 
 ;;;###autoload
 (defun file-cache-add-directory-using-find (directory)
diff --git a/lisp/gnus/ChangeLog b/lisp/gnus/ChangeLog
index 5f635e59cdf..dd493d383a3 100644
--- a/lisp/gnus/ChangeLog
+++ b/lisp/gnus/ChangeLog
@@ -1,3 +1,17 @@
+2012-11-16  Jan Tatarik  <jan.tatarik@gmail.com>
+
+        * gnus-score.el (gnus-score-body):
+        * gnus-logic.el (gnus-advanced-body): Don't score by headers when
+        scoring by body.
+
+2012-11-16  Glenn Morris  <rgm@gnu.org>
+
+        * gnus-diary.el (nndiary-request-create-group-functions)
+        (nndiary-request-update-info-functions)
+        (gnus-subscribe-newsgroup-functions)
+        (nndiary-request-accept-article-functions):
+        Use new names for hooks rather than obsolete aliases.
+
 2012-11-08  Katsumi Yamaoka  <yamaoka@jpl.org>
 
         * gnus-art.el (gnus-article-browse-html-parts): Always replace charset
diff --git a/lisp/gnus/gnus-diary.el b/lisp/gnus/gnus-diary.el
index 854af2f5d76..bca307b19b6 100644
--- a/lisp/gnus/gnus-diary.el
+++ b/lisp/gnus/gnus-diary.el
@@ -277,18 +277,18 @@ Optional prefix (or REVERSE argument) means sort in reverse order."
 
 ;; Called when a group is subscribed. This is needed because groups created
 ;; because of mail splitting are *not* created with the back end function.
-;; Thus, `nndiary-request-create-group-hooks' is inoperative.
+;; Thus, `nndiary-request-create-group-functions' is inoperative.
 (defun gnus-diary-maybe-update-group-parameters (group)
   (when (eq (car (gnus-find-method-for-group group)) 'nndiary)
     (gnus-diary-update-group-parameters group)))
 
-(add-hook 'nndiary-request-create-group-hooks
+(add-hook 'nndiary-request-create-group-functions
           'gnus-diary-update-group-parameters)
-;; Now that we have `gnus-subscribe-newsgroup-hooks', this is not needed
+;; Now that we have `gnus-subscribe-newsgroup-functions', this is not needed
 ;; anymore. Maybe I should remove this completely.
-(add-hook 'nndiary-request-update-info-hooks
+(add-hook 'nndiary-request-update-info-functions
           'gnus-diary-update-group-parameters)
-(add-hook 'gnus-subscribe-newsgroup-hooks
+(add-hook 'gnus-subscribe-newsgroup-functions
           'gnus-diary-maybe-update-group-parameters)
 
 
@@ -384,7 +384,7 @@ If ARG (or prefix) is non-nil, force prompting for all fields."
      nndiary-headers)
     ))
 
-(add-hook 'nndiary-request-accept-article-hooks
+(add-hook 'nndiary-request-accept-article-functions
           (lambda () (gnus-diary-check-message nil)))
 
 (define-key message-mode-map "\C-c\C-fd" 'gnus-diary-check-message)
diff --git a/lisp/gnus/gnus-logic.el b/lisp/gnus/gnus-logic.el
index a440b779930..60d7b31713b 100644
--- a/lisp/gnus/gnus-logic.el
+++ b/lisp/gnus/gnus-logic.el
@@ -181,17 +181,18 @@
   (with-current-buffer nntp-server-buffer
     (let* ((request-func (cond ((string= "head" header)
                                 'gnus-request-head)
-                               ;; We need to peek at the headers to detect the
-                               ;; content encoding
                                ((string= "body" header)
-                                'gnus-request-article)
+                                'gnus-request-body)
                                (t 'gnus-request-article)))
            ofunc article handles)
       ;; Not all backends support partial fetching.  In that case, we
       ;; just fetch the entire article.
-      (unless (gnus-check-backend-function
-               (intern (concat "request-" header))
-               gnus-newsgroup-name)
+      ;; When scoring by body, we need to peek at the headers to detect the
+      ;; content encoding
+      (unless (or (gnus-check-backend-function
+                   (intern (concat "request-" header))
+                   gnus-newsgroup-name)
+                  (string= "body" header))
         (setq ofunc request-func)
         (setq request-func 'gnus-request-article))
       (setq article (mail-header-number gnus-advanced-headers))
diff --git a/lisp/gnus/gnus-score.el b/lisp/gnus/gnus-score.el
index f215b845514..b7061960839 100644
--- a/lisp/gnus/gnus-score.el
+++ b/lisp/gnus/gnus-score.el
@@ -1762,21 +1762,22 @@ score in `gnus-newsgroup-scored' by SCORE."
                 (all-scores scores)
                 (request-func (cond ((string= "head" header)
                                      'gnus-request-head)
-                                    ;; We need to peek at the headers to detect
-                                    ;; the content encoding
                                     ((string= "body" header)
-                                     'gnus-request-article)
+                                     'gnus-request-body)
                                     (t 'gnus-request-article)))
                 entries alist ofunc article last)
            (when articles
              (setq last (mail-header-number (caar (last articles))))
              ;; Not all backends support partial fetching.  In that case,
              ;; we just fetch the entire article.
-             (unless (gnus-check-backend-function
-                      (and (string-match "^gnus-" (symbol-name request-func))
-                           (intern (substring (symbol-name request-func)
-                                              (match-end 0))))
-                      gnus-newsgroup-name)
+             ;; When scoring by body, we need to peek at the headers to detect
+             ;; the content encoding
+             (unless (or (gnus-check-backend-function
+                          (and (string-match "^gnus-" (symbol-name request-func))
+                               (intern (substring (symbol-name request-func)
+                                                  (match-end 0))))
+                          gnus-newsgroup-name)
+                         (string= "body" header))
                (setq ofunc request-func)
                (setq request-func 'gnus-request-article))
              (while articles
diff --git a/lisp/gnus/pop3.el b/lisp/gnus/pop3.el
index f95bf26ad1d..801ed66ec2b 100644
--- a/lisp/gnus/pop3.el
+++ b/lisp/gnus/pop3.el
@@ -178,7 +178,7 @@ Shorter values mean quicker response, but are more CPU intensive.")
                     1000))))))
 
 (defvar pop3-uidl)
-;; List of UIDLs of existing messages at pesent in the server:
+;; List of UIDLs of existing messages at present in the server:
 ;; ("UIDL1" "UIDL2" "UIDL3"...)
 
 (defvar pop3-uidl-saved)
diff --git a/lisp/help-mode.el b/lisp/help-mode.el
index c1ce5a521be..48c5849d301 100644
--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -677,7 +677,8 @@ help buffer."
                     " is also a " "face." "\n\n" facedoc))
           ;; Don't record the `describe-function' item in the stack.
           (setq help-xref-stack-item nil)
-          (help-setup-xref (list #'help-xref-interned symbol) nil)))))))
+          (help-setup-xref (list #'help-xref-interned symbol) nil))))
+      (goto-char (point-min)))))
 
 
 ;; Navigation/hyperlinking with xrefs
diff --git a/lisp/ibuffer.el b/lisp/ibuffer.el
index 72ca189e9d5..4e0ac1a4856 100644
--- a/lisp/ibuffer.el
+++ b/lisp/ibuffer.el
@@ -1362,24 +1362,27 @@ group."
 (defun ibuffer-mark-forward (arg)
   "Mark the buffer on this line, and move forward ARG lines.
 If point is on a group name, this function operates on that group."
-  (interactive "P")
-  (ibuffer-mark-interactive arg ibuffer-marked-char 1))
+  (interactive "p")
+  (ibuffer-mark-interactive arg ibuffer-marked-char))
 
 (defun ibuffer-unmark-forward (arg)
   "Unmark the buffer on this line, and move forward ARG lines.
 If point is on a group name, this function operates on that group."
-  (interactive "P")
-  (ibuffer-mark-interactive arg ?\s 1))
+  (interactive "p")
+  (ibuffer-mark-interactive arg ?\s))
 
 (defun ibuffer-unmark-backward (arg)
   "Unmark the buffer on this line, and move backward ARG lines.
 If point is on a group name, this function operates on that group."
-  (interactive "P")
-  (ibuffer-mark-interactive arg ?\s -1))
+  (interactive "p")
+  (ibuffer-unmark-forward (- arg)))
 
-(defun ibuffer-mark-interactive (arg mark movement)
+(defun ibuffer-mark-interactive (arg mark &optional movement)
   (ibuffer-assert-ibuffer-mode)
   (or arg (setq arg 1))
+  ;; deprecated movement argument
+  (when (and movement (< movement 0))
+    (setq arg (- arg)))
   (ibuffer-forward-line 0)
   (ibuffer-aif (get-text-property (point) 'ibuffer-filter-group-name)
       (progn
@@ -1389,8 +1392,12 @@ If point is on a group name, this function operates on that group."
     (let ((inhibit-read-only t))
       (while (> arg 0)
         (ibuffer-set-mark mark)
-        (ibuffer-forward-line movement t)
-        (setq arg (1- arg))))))
+        (ibuffer-forward-line 1 t)
+        (setq arg (1- arg)))
+      (while (< arg 0)
+        (ibuffer-forward-line -1 t)
+        (ibuffer-set-mark mark)
+        (setq arg (1+ arg))))))
 
 (defun ibuffer-set-mark (mark)
   (ibuffer-assert-ibuffer-mode)
diff --git a/lisp/imenu.el b/lisp/imenu.el
index 4686d1cf538..1d3da2db15b 100644
--- a/lisp/imenu.el
+++ b/lisp/imenu.el
@@ -546,9 +546,7 @@ The returned alist DOES NOT share structure with MENULIST."
 Return a split and sorted copy of ALIST.  The returned alist DOES
 NOT share structure with ALIST."
   (mapcar (lambda (elt)
-            (if (and (consp elt)
-                     (stringp (car elt))
-                     (listp (cdr elt)))
+            (if (imenu--subalist-p elt)
                 (imenu--split-menu (cdr elt) (car elt))
               elt))
           alist))
diff --git a/lisp/net/tramp-gvfs.el b/lisp/net/tramp-gvfs.el
index 60b39606d86..0aa1b8957ac 100644
--- a/lisp/net/tramp-gvfs.el
+++ b/lisp/net/tramp-gvfs.el
@@ -521,12 +521,12 @@ It is needed when D-Bus signals or errors arrive, because there
 is no information where to trace the message.")
 
 (defun tramp-gvfs-dbus-event-error (event err)
-  "Called when a D-Bus error message arrives, see `dbus-event-error-hooks'."
+  "Called when a D-Bus error message arrives, see `dbus-event-error-functions'."
   (when tramp-gvfs-dbus-event-vector
     (tramp-message tramp-gvfs-dbus-event-vector 10 "%S" event)
     (tramp-error tramp-gvfs-dbus-event-vector 'file-error "%s" (cadr err))))
 
-(add-hook 'dbus-event-error-hooks 'tramp-gvfs-dbus-event-error)
+(add-hook 'dbus-event-error-functions 'tramp-gvfs-dbus-event-error)
 
 
 ;; File name primitives.
diff --git a/lisp/play/gamegrid.el b/lisp/play/gamegrid.el
index f3e277e338c..a3ea4af4651 100644
--- a/lisp/play/gamegrid.el
+++ b/lisp/play/gamegrid.el
@@ -560,7 +560,7 @@ FILE is created there."
         (goto-char (point-min))
         (search-forward (concat (int-to-string score)
                                 " " (user-login-name) " "
-                                marker-string))
+                                marker-string) nil t)
         (beginning-of-line)))))
 
 (defun gamegrid-add-score-insecure (file score &optional directory)
diff --git a/lisp/progmodes/ruby-mode.el b/lisp/progmodes/ruby-mode.el
index 7c72b73a879..9d78b20ba4c 100644
--- a/lisp/progmodes/ruby-mode.el
+++ b/lisp/progmodes/ruby-mode.el
@@ -105,7 +105,10 @@
 (eval-and-compile
   (defconst ruby-here-doc-beg-re
   "\\(<\\)<\\(-\\)?\\(\\([a-zA-Z0-9_]+\\)\\|[\"]\\([^\"]+\\)[\"]\\|[']\\([^']+\\)[']\\)"
-    "Regexp to match the beginning of a heredoc."))
+  "Regexp to match the beginning of a heredoc.")
+
+  (defconst ruby-expression-expansion-re
+    "[^\\]\\(\\\\\\\\\\)*\\(#\\({[^}\n\\\\]*\\(\\\\.[^}\n\\\\]*\\)*}\\|\\(\\$\\|@\\|@@\\)\\(\\w\\|_\\)+\\)\\)"))
 
 (defun ruby-here-doc-end-match ()
   "Return a regexp to find the end of a heredoc.
@@ -384,7 +387,9 @@ and `\\' when preceded by `?'."
          (looking-at "class\\s *<<"))))
 
 (defun ruby-expr-beg (&optional option)
-  "TODO: document."
+  "Check if point is possibly at the beginning of an expression.
+OPTION specifies the type of the expression.
+Can be one of `heredoc', `modifier', `expr-qstr', `expr-re'."
   (save-excursion
     (store-match-data nil)
     (let ((space (skip-chars-backward " \t"))
@@ -397,10 +402,10 @@ and `\\' when preceded by `?'."
                (or (eq (char-syntax (char-before (point))) ?w)
                    (ruby-special-char-p))))
         nil)
-       ((and (eq option 'heredoc) (< space 0))
-        (not (progn (goto-char start) (ruby-singleton-class-p))))
-       ((or (looking-at ruby-operator-re)
-            (looking-at "[\\[({,;]")
+       ((looking-at ruby-operator-re))
+       ((eq option 'heredoc)
+        (and (< space 0) (not (ruby-singleton-class-p start))))
+       ((or (looking-at "[\\[({,;]")
             (and (looking-at "[!?]")
                  (or (not (eq option 'modifier))
                      (bolp)
@@ -865,39 +870,54 @@ calculating indentation on the lines after it."
                 (beginning-of-line)))))
 
 (defun ruby-move-to-block (n)
-  "Move to the beginning (N < 0) or the end (N > 0) of the current block
-or blocks containing the current block."
-  ;; TODO: Make this work for n > 1,
-  ;; make it not loop for n = 0,
-  ;; document body
+  "Move to the beginning (N < 0) or the end (N > 0) of the
+current block, a sibling block, or an outer block.  Do that (abs N) times."
   (let ((orig (point))
         (start (ruby-calculate-indent))
-        (down (looking-at (if (< n 0) ruby-block-end-re
-                            (concat "\\<\\(" ruby-block-beg-re "\\)\\>"))))
-        pos done)
-    (while (and (not done) (not (if (< n 0) (bobp) (eobp))))
-      (forward-line n)
-      (cond
-       ((looking-at "^\\s *$"))
-       ((looking-at "^\\s *#"))
-       ((and (> n 0) (looking-at "^=begin\\>"))
-        (re-search-forward "^=end\\>"))
-       ((and (< n 0) (looking-at "^=end\\>"))
-        (re-search-backward "^=begin\\>"))
-       (t
-        (setq pos (current-indentation))
+        (signum (if (> n 0) 1 -1))
+        (backward (< n 0))
+        down pos done)
+    (dotimes (_ (abs n))
+      (setq done nil)
+      (setq down (save-excursion
+                   (back-to-indentation)
+                   ;; There is a block start or block end keyword on this
+                   ;; line, don't need to look for another block.
+                   (and (re-search-forward
+                         (if backward ruby-block-end-re
+                           (concat "\\_<\\(" ruby-block-beg-re "\\)\\_>"))
+                         (line-end-position) t)
+                        (not (nth 8 (syntax-ppss))))))
+      (while (and (not done) (not (if backward (bobp) (eobp))))
+        (forward-line signum)
         (cond
-         ((< start pos)
-          (setq down t))
-         ((and down (= pos start))
-          (setq done t))
-         ((> start pos)
-          (setq done t)))))
-      (if done
-          (save-excursion
-            (back-to-indentation)
-            (if (looking-at (concat "\\<\\(" ruby-block-mid-re "\\)\\>"))
-                (setq done nil)))))
+         ;; Skip empty and commented out lines.
+         ((looking-at "^\\s *$"))
+         ((looking-at "^\\s *#"))
+         ;; Skip block comments;
+         ((and (not backward) (looking-at "^=begin\\>"))
+          (re-search-forward "^=end\\>"))
+         ((and backward (looking-at "^=end\\>"))
+          (re-search-backward "^=begin\\>"))
+         (t
+          (setq pos (current-indentation))
+          (cond
+           ;; Deeper indentation, we found a block.
+           ;; FIXME: We can't recognize empty blocks this way.
+           ((< start pos)
+            (setq down t))
+           ;; Block found, and same indentation as when started, stop.
+           ((and down (= pos start))
+            (setq done t))
+           ;; Shallower indentation, means outer block, can stop now.
+           ((> start pos)
+            (setq done t)))))
+        (if done
+            (save-excursion
+              (back-to-indentation)
+              ;; Not really at the first or last line of the block, move on.
+              (if (looking-at (concat "\\<\\(" ruby-block-mid-re "\\)\\>"))
+                  (setq done nil))))))
     (back-to-indentation)))
 
 (defun ruby-beginning-of-block (&optional arg)
@@ -909,8 +929,7 @@ With ARG, move up multiple blocks."
 (defun ruby-end-of-block (&optional arg)
   "Move forward to the end of the current block.
 With ARG, move out of multiple blocks."
-  ;; Passing a value > 1 to ruby-move-to-block currently doesn't work.
-  (interactive)
+  (interactive "p")
   (ruby-move-to-block (or arg 1)))
 
 (defun ruby-forward-sexp (&optional arg)
@@ -1233,7 +1252,19 @@ It will be properly highlighted even when the call omits parens."))
           ;; Handle percent literals: %w(), %q{}, etc.
           ((concat "\\(?:^\\|[[ \t\n<+(,=]\\)" ruby-percent-literal-beg-re)
            (1 (prog1 "|" (ruby-syntax-propertize-percent-literal end)))))
-         (point) end))
+         (point) end)
+        (remove-text-properties start end '(ruby-expansion-match-data))
+        (goto-char start)
+        ;; Find all expression expansions and
+        ;; - set the syntax of all text inside to whitespace,
+        ;; - save the match data to a text property, for font-locking later.
+        (while (re-search-forward ruby-expression-expansion-re end 'move)
+          (when (ruby-in-ppss-context-p 'string)
+            (put-text-property (match-beginning 2) (match-end 2)
+                               'syntax-table (string-to-syntax "-"))
+            (put-text-property (match-beginning 2) (1+ (match-beginning 2))
+                               'ruby-expansion-match-data
+                               (match-data)))))
 
       (defun ruby-syntax-propertize-heredoc (limit)
         (let ((ppss (syntax-ppss))
@@ -1566,7 +1597,7 @@ See `font-lock-syntax-table'.")
    '("\\(^\\s *\\|[\[\{\(,]\\s *\\|\\sw\\s +\\)\\(\\(\\sw\\|_\\)+\\):[^:]" 2 font-lock-constant-face)
    ;; expression expansion
    '(ruby-match-expression-expansion
-     0 font-lock-variable-name-face t)
+     2 font-lock-variable-name-face t)
    ;; warn lower camel case
                                         ;'("\\<[a-z]+[a-z0-9]*[A-Z][A-Za-z0-9]*\\([!?]?\\|\\>\\)"
                                         ;  0 font-lock-warning-face)
@@ -1574,9 +1605,14 @@ See `font-lock-syntax-table'.")
   "Additional expressions to highlight in Ruby mode.")
 
 (defun ruby-match-expression-expansion (limit)
-  (when (re-search-forward "[^\\]\\(\\\\\\\\\\)*\\(#\\({[^}\n\\\\]*\\(\\\\.[^}\n\\\\]*\\)*}\\|\\(\\$\\|@\\|@@\\)\\(\\w\\|_\\)+\\)\\)" limit 'move)
-    (or (ruby-in-ppss-context-p 'string)
-        (ruby-match-expression-expansion limit))))
+  (let ((prop 'ruby-expansion-match-data) pos value)
+    (when (and (setq pos (next-single-char-property-change (point) prop
+                                                           nil limit))
+               (> pos (point)))
+      (goto-char pos)
+      (or (and (setq value (get-text-property pos prop))
+               (progn (set-match-data value) t))
+          (ruby-match-expression-expansion limit)))))
 
 ;;;###autoload
 (define-derived-mode ruby-mode prog-mode "Ruby"
diff --git a/lisp/subr.el b/lisp/subr.el
index 48d208235dd..1a850b1eabf 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -3972,11 +3972,16 @@ The properties used on SYMBOL are `composefunc', `sendfunc',
   (put symbol 'hookvar (or hookvar 'mail-send-hook)))
 
 (defun set-temporary-overlay-map (map &optional keep-pred)
-  "Set MAP as a temporary overlay map.
-When KEEP-PRED is `t', using a key from the temporary keymap
-leaves this keymap activated.  KEEP-PRED can also be a function,
-which will have the same effect when it returns `t'.
-When KEEP-PRED is nil, the temporary keymap is used only once."
+  "Set MAP as a temporary keymap taking precedence over most other keymaps.
+Note that this does NOT take precedence over the \"overriding\" maps
+`overriding-terminal-local-map' and `overriding-local-map' (or the
+`keymap' text property).  Unlike those maps, if no match for a key is
+found in MAP, the normal key lookup sequence then continues.
+
+Normally, MAP is used only once.  If the optional argument
+KEEP-PRED is t, MAP stays active if a key from MAP is used.
+KEEP-PRED can also be a function of no arguments: if it returns
+non-nil then MAP stays active."
   (let* ((clearfunsym (make-symbol "clear-temporary-overlay-map"))
          (overlaysym (make-symbol "t"))
          (alist (list (cons overlaysym map)))
diff --git a/lisp/term.el b/lisp/term.el
index e6466b8fa95..d6acaef1ae9 100644
--- a/lisp/term.el
+++ b/lisp/term.el
@@ -4178,11 +4178,16 @@ the process.  Any more args are arguments to PROGRAM."
   (term-mode)
   (term-char-mode)
 
-  ;; I wanna have find-file on C-x C-f -mm
-  ;; your mileage may definitely vary, maybe it's better to put this in your
-  ;; .emacs ...
-
-  (term-set-escape-char ?\C-x)
+  ;; Historical baggage.  A call to term-set-escape-char used to not
+  ;; undo any previous call to t-s-e-c.  Because of this, ansi-term
+  ;; ended up with both C-x and C-c as escape chars.  Who knows what
+  ;; the original intention was, but people could have become used to
+  ;; either.   (Bug#12842)
+  (let (term-escape-char)
+    ;; I wanna have find-file on C-x C-f -mm
+    ;; your mileage may definitely vary, maybe it's better to put this in your
+    ;; .emacs ...
+    (term-set-escape-char ?\C-x))
 
   (switch-to-buffer term-ansi-buffer-name))
 
diff --git a/lisp/term/w32-win.el b/lisp/term/w32-win.el
index ad6e1125027..224fb7c1442 100644
--- a/lisp/term/w32-win.el
+++ b/lisp/term/w32-win.el
@@ -116,7 +116,7 @@
                                    "/")
                      "/")))
                 (dnd-handle-one-url window 'private
-                                    (concat "file:" file-name)))
+                                    (concat "file://" file-name)))
 
 (defun w32-drag-n-drop (event &optional new-frame)
   "Edit the files listed in the drag-n-drop EVENT.
diff --git a/lisp/window.el b/lisp/window.el
index 30ee622cfe6..9ac3a4ecda0 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -2571,8 +2571,7 @@ move it as far as possible in the desired direction."
 Interactively, if no argument is given, make the selected window
 one line taller.  If optional argument HORIZONTAL is non-nil,
 make selected window wider by DELTA columns.  If DELTA is
-negative, shrink selected window by -DELTA lines or columns.
-Return nil."
+negative, shrink selected window by -DELTA lines or columns."
   (interactive "p")
   (let ((minibuffer-window (minibuffer-window)))
     (cond
@@ -2605,8 +2604,7 @@ Interactively, if no argument is given, make the selected window
 one line smaller.  If optional argument HORIZONTAL is non-nil,
 make selected window narrower by DELTA columns.  If DELTA is
 negative, enlarge selected window by -DELTA lines or columns.
-Also see the `window-min-height' variable.
-Return nil."
+Also see the `window-min-height' variable."
   (interactive "p")
   (let ((minibuffer-window (minibuffer-window)))
     (cond
@@ -3049,8 +3047,10 @@ WINDOW must be a live window and defaults to the selected one."
                                 (set-marker (nth 2 entry) point))
                         ;; Make new markers.
                         (list (copy-marker start)
-                              (copy-marker point)))))
-
+                              (copy-marker
+                               ;; Preserve window-point-insertion-type
+                               ;; (Bug#12588).
+                               point window-point-insertion-type)))))
           (set-window-prev-buffers
            window (cons entry (window-prev-buffers window))))))))
 
@@ -4555,13 +4555,17 @@ element is BUFFER."
           ;; If WINDOW has a quit-restore parameter, reset its car.
           (setcar (window-parameter window 'quit-restore) 'same))
       ;; WINDOW shows another buffer.
-      (set-window-parameter
-       window 'quit-restore
-       (list 'other
-             ;; A quadruple of WINDOW's buffer, start, point and height.
-             (list (window-buffer window) (window-start window)
-                   (window-point window) (window-total-size window))
-             (selected-window) buffer))))
+      (with-current-buffer (window-buffer window)
+        (set-window-parameter
+         window 'quit-restore
+         (list 'other
+               ;; A quadruple of WINDOW's buffer, start, point and height.
+               (list (current-buffer) (window-start window)
+                     ;; Preserve window-point-insertion-type (Bug#12588).
+                     (copy-marker
+                      (window-point window) window-point-insertion-type)
+                     (window-total-size window))
+               (selected-window) buffer)))))
    ((eq type 'window)
     ;; WINDOW has been created on an existing frame.
     (set-window-parameter
@@ -5170,11 +5174,12 @@ is higher than WINDOW."
       (error nil))))
 
 (defun window--display-buffer (buffer window type &optional alist dedicated)
-  "Display BUFFER in WINDOW and make its frame visible.
+  "Display BUFFER in WINDOW.
 TYPE must be one of the symbols `reuse', `window' or `frame' and
-is passed unaltered to `display-buffer-record-window'. Set
-`window-dedicated-p' to DEDICATED if non-nil.  Return WINDOW if
-BUFFER and WINDOW are live."
+is passed unaltered to `display-buffer-record-window'.  ALIST is
+the alist argument of `display-buffer'.  Set `window-dedicated-p'
+to DEDICATED if non-nil.  Return WINDOW if BUFFER and WINDOW are
+live."
   (when (and (buffer-live-p buffer) (window-live-p window))
     (display-buffer-record-window type window buffer)
     (unless (eq buffer (window-buffer window))
@@ -5187,10 +5192,10 @@ BUFFER and WINDOW are live."
     (let ((parameter (window-parameter window 'quit-restore))
           (height (cdr (assq 'window-height alist)))
           (width (cdr (assq 'window-width alist))))
-      (when (or (memq type '(window frame))
+      (when (or (eq type 'window)
                 (and (eq (car parameter) 'same)
-                     (memq (nth 1 parameter) '(window frame))))
-        ;; Adjust height of new window or frame.
+                     (eq (nth 1 parameter) 'window)))
+        ;; Adjust height of window if asked for.
         (cond
          ((not height))
          ((numberp height)
@@ -5201,19 +5206,12 @@ BUFFER and WINDOW are live."
                      (* (window-total-size (frame-root-window window))
                         height))))
                  (delta (- new-height (window-total-size window))))
-            (cond
-             ((and (window--resizable-p window delta nil 'safe)
-                   (window-combined-p window))
-              (window-resize window delta nil 'safe))
-             ((or (eq type 'frame)
-                  (and (eq (car parameter) 'same)
-                       (eq (nth 1 parameter) 'frame)))
-              (set-frame-height
-               (window-frame window)
-               (+ (frame-height (window-frame window)) delta))))))
+            (when (and (window--resizable-p window delta nil 'safe)
+                       (window-combined-p window))
+              (window-resize window delta nil 'safe))))
          ((functionp height)
           (ignore-errors (funcall height window))))
-        ;; Adjust width of a window or frame.
+        ;; Adjust width of window if asked for.
         (cond
          ((not width))
          ((numberp width)
@@ -5224,18 +5222,12 @@ BUFFER and WINDOW are live."
                      (* (window-total-size (frame-root-window window) t)
                         width))))
                  (delta (- new-width (window-total-size window t))))
-            (cond
-             ((and (window--resizable-p window delta t 'safe)
-                   (window-combined-p window t))
-              (window-resize window delta t 'safe))
-             ((or (eq type 'frame)
-                  (and (eq (car parameter) 'same)
-                       (eq (nth 1 parameter) 'frame)))
-              (set-frame-width
-               (window-frame window)
-               (+ (frame-width (window-frame window)) delta))))))
+            (when (and (window--resizable-p window delta t 'safe)
+                       (window-combined-p window t))
+              (window-resize window delta t 'safe))))
          ((functionp width)
           (ignore-errors (funcall width window))))))
+
     window))
 
 (defun window--maybe-raise-frame (frame)
@@ -5295,13 +5287,19 @@ See `display-buffer' for details.")
   "Alist of conditional actions for `display-buffer'.
 This is a list of elements (CONDITION . ACTION), where:
 
- CONDITION is either a regexp matching buffer names, or a function
-  that takes a buffer and returns a boolean.
+ CONDITION is either a regexp matching buffer names, or a
+  function that takes two arguments - a buffer name and the
+  ACTION argument of `display-buffer' - and returns a boolean.
 
  ACTION is a cons cell (FUNCTION . ALIST), where FUNCTION is a
   function or a list of functions.  Each such function should
   accept two arguments: a buffer to display and an alist of the
-  same form as ALIST.  See `display-buffer' for details."
+  same form as ALIST.  See `display-buffer' for details.
+
+`display-buffer' scans this alist until it either finds a
+matching regular expression or the function specified by a
+condition returns non-nil.  In any of these cases, it adds the
+associated action to the list of actions it will try."
   :type `(alist :key-type
                 (choice :tag "Condition"
                         regexp
@@ -5335,15 +5333,16 @@ specified, e.g. by the user options `display-buffer-alist' or
 `display-buffer-base-action'.  See `display-buffer'.")
 (put 'display-buffer-fallback-action 'risky-local-variable t)
 
-(defun display-buffer-assq-regexp (buffer-name alist)
-  "Retrieve ALIST entry corresponding to BUFFER-NAME."
+(defun display-buffer-assq-regexp (buffer-name alist action)
+  "Retrieve ALIST entry corresponding to BUFFER-NAME.
+ACTION is the action argument passed to `display-buffer'."
   (catch 'match
     (dolist (entry alist)
       (let ((key (car entry)))
         (when (or (and (stringp key)
                        (string-match-p key buffer-name))
-                  (and (symbolp key) (functionp key)
-                       (funcall key buffer-name alist)))
+                  (and (functionp key)
+                       (funcall key buffer-name action)))
           (throw 'match (cdr entry)))))))
 
 (defvar display-buffer--same-window-action
@@ -5453,8 +5452,8 @@ argument, ACTION is t."
         (funcall display-buffer-function buffer inhibit-same-window)
       ;; Otherwise, use the defined actions.
       (let* ((user-action
-              (display-buffer-assq-regexp (buffer-name buffer)
-                                          display-buffer-alist))
+              (display-buffer-assq-regexp
+               (buffer-name buffer) display-buffer-alist action))
              (special-action (display-buffer--special-action buffer))
              ;; Extra actions from the arguments to this function:
              (extra-action
@@ -6068,22 +6067,26 @@ of `fit-frame-to-buffer-max-height' and `window-min-height'."
   :group 'help)
 
 (defcustom fit-frame-to-buffer-bottom-margin 4
-  "Bottom margin for `fit-frame-to-buffer'.
-This is the number of lines `fit-frame-to-buffer' leaves free at the
-bottom of the display in order to not obscure the system task bar."
+  "Bottom margin for the command `fit-frame-to-buffer'.
+This is the number of lines that function leaves free at the bottom of
+the display, in order to not obscure any system task bar or panel.
+If you do not have one (or if it is vertical) you might want to
+reduce this.  If it is thicker, you might want to increase this."
+  ;; If you set this too small, fit-frame-to-buffer can shift the
+  ;; frame up to avoid the panel.
   :type 'integer
   :version "24.3"
   :group 'windows)
 
 (defun fit-frame-to-buffer (&optional frame max-height min-height)
-  "Adjust height of FRAME to display its buffer's contents exactly.
+  "Adjust height of FRAME to display its buffer contents exactly.
 FRAME can be any live frame and defaults to the selected one.
 
-Optional argument MAX-HEIGHT specifies the maximum height of
-FRAME and defaults to the height of the display below the current
-top line of FRAME minus FIT-FRAME-TO-BUFFER-BOTTOM-MARGIN.
-Optional argument MIN-HEIGHT specifies the minimum height of
-FRAME."
+Optional argument MAX-HEIGHT specifies the maximum height of FRAME.
+It defaults to the height of the display below the current
+top line of FRAME, minus `fit-frame-to-buffer-bottom-margin'.
+Optional argument MIN-HEIGHT specifies the minimum height of FRAME.
+The default corresponds to `window-min-height'."
   (interactive)
   (setq frame (window-normalize-frame frame))
   (let* ((root (frame-root-window frame))
@@ -6160,6 +6163,10 @@ defaults to `window-min-height'.  Both MAX-HEIGHT and MIN-HEIGHT
 are specified in lines and include the mode line and header line,
 if any.
 
+If WINDOW is a full height window, then if the option
+`fit-frame-to-buffer' is non-nil, this calls the function
+`fit-frame-to-buffer' to adjust the frame height.
+
 Return the number of lines by which WINDOW was enlarged or
 shrunk.  If an error occurs during resizing, return nil but don't
 signal an error.
diff --git a/lisp/woman.el b/lisp/woman.el
index 974a7d72465..46b6b680440 100644
--- a/lisp/woman.el
+++ b/lisp/woman.el
@@ -1303,12 +1303,12 @@ cache to be re-read."
        ((null (cdr files)) (car (car files))) ; only 1 file for topic.
        (t
         ;; Multiple files for topic, so must select 1.
-        ;; Unread the command event (TAB = ?\t = 9) that runs the command
-        ;; `minibuffer-complete' in order to automatically complete the
-        ;; minibuffer contents as far as possible.
-        (setq unread-command-events '(9)) ; and delete any type-ahead!
-        (completing-read "Manual file: " files nil 1
-                         (try-completion "" files) 'woman-file-history))))))
+        ;; Run the command `minibuffer-complete' in order to automatically
+        ;; complete the minibuffer contents as far as possible.
+        (minibuffer-with-setup-hook
+            (lambda () (let ((this-command this-command)) (minibuffer-complete)))
+          (completing-read "Manual file: " files nil 1
+                           (try-completion "" files) 'woman-file-history)))))))
 
 (defun woman-select (predicate list)
   "Select unique elements for which PREDICATE is true in LIST.