Merge from origin/emacs-26

1908173 (origin/emacs-26) Fix Bug#32828
7f5086d * lisp/net/shr.el (shr-copy-url): Fix docstring.
d309994 Fix typos in documentation
25cdd65 ; Spellcheck two more documentation strings
c8bda05 ; * lisp/simple.el (save-interprogram-paste-before-kill): Fix...
dc7fdee * doc/emacs/kmacro.texi (Basic Keyboard Macro): Mention old b...
17766a1 Improve docs of functions/variables related to 'display-buffer'
a363931 * lisp/mouse.el (tear-off-window): Fix non-mouse use (bug#32799)
8b8a4c0 Improve documentation of directory-local variables
c9c9756 Don't use obsolete variable 'save-place' in documentation
ca208e8 Use save-place-mode instead of save-place

26 files changed, 113 insertions, 72 deletions

diff --git a/CONTRIBUTE b/CONTRIBUTE
index c4f424ce560..0b68052a0cd 100644
--- a/CONTRIBUTE
+++ b/CONTRIBUTE
@@ -97,7 +97,7 @@ Otherwise do not mark it.
 If your change requires updating the manuals to document new
 functions/commands/variables/faces, then use the proper Texinfo
 command to index them; for instance, use @vindex for variables and
-@findex for functions/commands.  For the full list of predefine indices, see
+@findex for functions/commands.  For the full list of predefined indices, see
 https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Predefined-Indices.html
 or run the shell command 'info "(texinfo)Predefined Indices"'.
 
diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index 51e36ea4b75..ddde5b22e6b 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -1059,6 +1059,10 @@ local variable specifications; it automatically makes these variables
 local to the buffer, and sets them to the values specified in the
 file.
 
+  File local variables override directory local variables
+(@pxref{Directory Variables}), if any are specified for a file's
+directory.
+
 @menu
 * Specifying File Variables:: Specifying file local variables.
 * Safe File Variables::       Making sure file local variables are safe.
@@ -1309,7 +1313,12 @@ confirmation about processing @code{eval} variables.
   Sometimes, you may wish to define the same set of local variables to
 all the files in a certain directory and its subdirectories, such as
 the directory tree of a large software project.  This can be
-accomplished with @dfn{directory-local variables}.
+accomplished with @dfn{directory-local variables}.  File local
+variables override directory local variables, so if some of the files
+in a directory need specialized settings, you can specify the settings
+for the majority of the directory's files in directory variables, and
+then define file local variables in a few files which need the general
+settings overridden.
 
 @cindex @file{.dir-locals.el} file
   The usual way to define directory-local variables is to put a file
diff --git a/doc/emacs/kmacro.texi b/doc/emacs/kmacro.texi
index dac41fdb873..0151c816a89 100644
--- a/doc/emacs/kmacro.texi
+++ b/doc/emacs/kmacro.texi
@@ -49,15 +49,19 @@ intelligent or general.  For such things, Lisp must be used.
 
 @table @kbd
 @item @key{F3}
+@itemx C-x (
 Start defining a keyboard macro
 (@code{kmacro-start-macro-or-insert-counter}).
 @item @key{F4}
+@itemx C-x e
 If a keyboard macro is being defined, end the definition; otherwise,
 execute the most recent keyboard macro
 (@code{kmacro-end-or-call-macro}).
 @item C-u @key{F3}
+@itemx C-u C-x (
 Re-execute last keyboard macro, then append keys to its definition.
 @item C-u C-u @key{F3}
+@itemx C-u C-u C-x (
 Append keys to the last keyboard macro without re-executing it.
 @item C-x C-k r
 Run the last keyboard macro on each line that begins in the region
diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 8a6cf73af51..0f7502f1c20 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -791,7 +791,7 @@ Here are some important details about that usage.
 
 @enumerate
 @item When @var{symbol} occurs more than once in @var{seqpat},
-the second and subsequent occurances do not expand to re-binding,
+the second and subsequent occurrences do not expand to re-binding,
 but instead expand to an equality test using @code{eq}.
 
 The following example features a @code{pcase} form
diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi
index b3528b12d57..1cc7cb65b5f 100644
--- a/doc/lispref/customize.texi
+++ b/doc/lispref/customize.texi
@@ -449,15 +449,14 @@ those other variables already have their intended values.
   It is useful to specify the @code{:require} keyword for an option
 that turns on a certain feature.  This causes Emacs to load the
 feature, if it is not already loaded, whenever the option is set.
-@xref{Common Keywords}.  Here is an example, from the library
-@file{saveplace.el}:
+@xref{Common Keywords}.  Here is an example:
 
 @example
-(defcustom save-place nil
-  "Non-nil means automatically save place in each file..."
+(defcustom frobnicate-automatically nil
+  "Non-nil means automatically frobnicate all buffers."
   :type 'boolean
-  :require 'saveplace
-  :group 'save-place)
+  :require 'frobnicate-mode
+  :group 'frobnicate)
 @end example
 
 If a customization item has a type such as @code{hook} or
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 67b78aea747..400e6bb45c0 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -3039,7 +3039,7 @@ Although Emacs normally respects access permissions of the underlying
 operating system, in some cases it handles accesses specially.  For
 example, file names can have handlers that treat the files specially,
 with their own access checking.  @xref{Magic File Names}.  Also, a
-buffer can be read-only even if the corresponding file is writeable,
+buffer can be read-only even if the corresponding file is writable,
 and vice versa, which can result in messages such as @samp{File passwd
 is write-protected; try to save anyway? (yes or no)}.  @xref{Read Only
 Buffers}.
diff --git a/doc/man/emacsclient.1 b/doc/man/emacsclient.1
index daaacab7f3e..5aaa6d1f083 100644
--- a/doc/man/emacsclient.1
+++ b/doc/man/emacsclient.1
@@ -1,7 +1,7 @@
 .\" See section COPYING for conditions for redistribution.
 .TH EMACSCLIENT 1
 .\" NAME should be all caps, SECTION should be 1-8, maybe w/ subsection
-.\" other parms are allowed: see man(7), man(1)
+.\" other params are allowed: see man(7), man(1)
 .SH NAME
 emacsclient \- tells a running Emacs to visit a file
 .SH SYNOPSIS
diff --git a/doc/misc/calc.texi b/doc/misc/calc.texi
index 446210e5ff4..83807c6fd28 100644
--- a/doc/misc/calc.texi
+++ b/doc/misc/calc.texi
@@ -36249,7 +36249,7 @@ keystrokes are not listed in this summary.
 @c
 @r{       @:      j +   @:formula      @:    27  @:calc-sel-add-both-sides@:}
 @r{       @:      j -   @:formula      @:    27  @:calc-sel-sub-both-sides@:}
-@r{       @:      j *   @:formula      @:    27  @:calc-sel-mul-both-sides@:}
+@r{       @:      j *   @:formula      @:    27  @:calc-sel-mult-both-sides@:}
 @r{       @:      j /   @:formula      @:    27  @:calc-sel-div-both-sides@:}
 @r{       @:      j &   @:             @:    27  @:calc-sel-invert@:}
 
diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi
index 79aac9b31fc..c19d5e1a437 100644
--- a/doc/misc/eshell.texi
+++ b/doc/misc/eshell.texi
@@ -851,7 +851,7 @@ since.
 
 Make it so that the Lisp command on the right of the pipe is repeatedly
 called with the input strings as arguments.  This will require changing
-@code{eshell-do-pipeline} to handle non-process targets.
+@code{eshell-do-pipelines} to handle non-process targets.
 
 @item Input redirection is not supported
 
diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi
index 40cc44a12e7..2f7d8407fc4 100644
--- a/doc/misc/gnus.texi
+++ b/doc/misc/gnus.texi
@@ -4457,7 +4457,7 @@ generated.  It may be used to modify the buffer in some strange,
 unnatural way.
 
 @item gnus-group-prepared-hook
-@vindex gnus-group-prepare-hook
+@vindex gnus-group-prepared-hook
 is called as the very last thing after the group buffer has been
 generated.  It may be used to move point around, for instance.
 
diff --git a/doc/misc/org.texi b/doc/misc/org.texi
index 3bce0dd7369..ccb5f88f93d 100644
--- a/doc/misc/org.texi
+++ b/doc/misc/org.texi
@@ -17991,7 +17991,7 @@ supports Imenu menus.  Enable it with a mode hook as follows:
 @end lisp
 @vindex org-imenu-depth
 By default the Imenu index is two levels deep.  Change the index depth using
-thes variable, @code{org-imenu-depth}.
+the variable @code{org-imenu-depth}.
 @item @file{speedbar.el} by Eric M. Ludlam
 @cindex @file{speedbar.el}
 @cindex Ludlam, Eric M.
@@ -18065,7 +18065,7 @@ different replacement keys, look at the variable @code{org-disputed-keys}.
 @cindex @file{ecomplete.el}
 
 Ecomplete provides ``electric'' address completion in address header
-lines in message buffers.  Sadly Orgtbl mode cuts ecompletes power
+lines in message buffers.  Sadly Orgtbl mode cuts ecomplete's power
 supply: No completion happens when Orgtbl mode is enabled in message
 buffers while entering text in address header lines.  If one wants to
 use ecomplete one should @emph{not} follow the advice to automagically
diff --git a/doc/misc/reftex.texi b/doc/misc/reftex.texi
index 2ea98cf5df1..4367d773e63 100644
--- a/doc/misc/reftex.texi
+++ b/doc/misc/reftex.texi
@@ -4618,7 +4618,7 @@ return the string to insert into the buffer.
 
 @defopt reftex-cite-prompt-optional-args
 Non-@code{nil} means, prompt for empty optional arguments in cite macros.
-When an entry in @code{reftex-cite-format} ist given with square brackets to
+When an entry in @code{reftex-cite-format} is given with square brackets to
 indicate optional arguments (for example @samp{\\cite[][]@{%l@}}), RefTeX can
 prompt for values.  Possible values are:
 @example
diff --git a/doc/misc/sieve.texi b/doc/misc/sieve.texi
index 2d290b36885..cad3cd86469 100644
--- a/doc/misc/sieve.texi
+++ b/doc/misc/sieve.texi
@@ -127,7 +127,7 @@ bindings to manage Sieve scripts remotely. @xref{Managing Sieve}.
 @kindex C-c RET
 @findex sieve-manage
 @cindex manage remote sieve script
-Open a connection to a remote server using the Managesieve protocol.
+Open a connection to a remote server using the Manage Sieve protocol.
 
 @item C-c C-l
 @kindex C-c C-l
diff --git a/doc/misc/srecode.texi b/doc/misc/srecode.texi
index 2987f629747..7d8416e9013 100644
--- a/doc/misc/srecode.texi
+++ b/doc/misc/srecode.texi
@@ -1474,7 +1474,7 @@ to write your own function in order to provide your dictionaries with
 the values needed for custom templates.
 
 In this way, you can build your own code generator for any language
-based on a set of predefined macros whos values you need to derive
+based on a set of predefined macros whose values you need to derive
 from Emacs Lisp code yourself.
 
 For example:
diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi
index ca402013c71..88fa55fdeeb 100644
--- a/doc/misc/tramp.texi
+++ b/doc/misc/tramp.texi
@@ -301,7 +301,7 @@ into a buffer, and then deletes the temporary file.
 
 @item
 Edit, modify, change the buffer contents as normal, and then save the
-buffer wth @kbd{C-x C-s}.
+buffer with @kbd{C-x C-s}.
 
 @item
 @value{tramp} transfers the buffer contents to the remote host in
diff --git a/doc/misc/url.texi b/doc/misc/url.texi
index a8ac1179751..eaeae603526 100644
--- a/doc/misc/url.texi
+++ b/doc/misc/url.texi
@@ -1342,7 +1342,7 @@ The User Agent string used for sending @acronym{HTTP}/@acronym{HTTPS}
 requests.  The value should be @code{nil}, which means that no
 @samp{User-Agent} header is generated, @code{default}, which means
 that a string is generated based on the setting of
-@code{url-privacy-leve}, a string or a function of no arguments that
+@code{url-privacy-level}, a string or a function of no arguments that
 returns a string.
 
 The default is @code{default}, which means that the
diff --git a/doc/misc/vhdl-mode.texi b/doc/misc/vhdl-mode.texi
index 8fc75106d52..c0efdbf75f4 100644
--- a/doc/misc/vhdl-mode.texi
+++ b/doc/misc/vhdl-mode.texi
@@ -734,7 +734,7 @@ operator on the first line of the statement.  Here is the lisp code
 Custom indent functions take a single argument, which is a syntactic
 component cons cell (see @ref{Syntactic Analysis}).  The
 function returns an integer offset value that will be added to the
-running total indentation for the lne.  Note that what actually gets
+running total indentation for the line.  Note that what actually gets
 returned is the difference between the column that the signal assignment
 operator is on, and the column of the buffer relative position passed in
 the function's argument.  Remember that VHDL Mode automatically
diff --git a/lisp/files.el b/lisp/files.el
index 7efbf05b1a6..b8f6c461467 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -490,7 +490,8 @@ The functions are called in the order given until one of them returns non-nil.")
 (defcustom find-file-hook nil
   "List of functions to be called after a buffer is loaded from a file.
 The buffer's local variables (if any) will have been processed before the
-functions are called."
+functions are called.  This includes directory-local variables, if any,
+for the file's directory."
   :group 'find-file
   :type 'hook
   :options '(auto-insert)
@@ -2431,7 +2432,7 @@ the file contents into it using `insert-file-contents-literally'."
                                   _after-find-file-from-revert-buffer
                                   nomodes)
   "Called after finding a file and by the default revert function.
-Sets buffer mode, parses local variables.
+Sets buffer mode, parses file-local and directory-local variables.
 Optional args ERROR, WARN, and NOAUTO: ERROR non-nil means there was an
 error in reading the file.  WARN non-nil means warn if there
 exists an auto-save file more recent than the visited file.
@@ -2516,7 +2517,7 @@ unless NOMODES is non-nil."
 
 (defun normal-mode (&optional find-file)
   "Choose the major mode for this buffer automatically.
-Also sets up any specified local variables of the file.
+Also sets up any specified local variables of the file or its directory.
 Uses the visited file name, the -*- line, and the local variables spec.
 
 This function is called automatically from `find-file'.  In that case,
@@ -3547,6 +3548,8 @@ DIR-NAME is the name of the associated directory.  Otherwise it is nil."
 
 (defun hack-local-variables (&optional handle-mode)
   "Parse and put into effect this buffer's local variables spec.
+For buffers visiting files, also puts into effect directory-local
+variables.
 Uses `hack-local-variables-apply' to apply the variables.
 
 If HANDLE-MODE is nil, we apply all the specified local
diff --git a/lisp/menu-bar.el b/lisp/menu-bar.el
index 74e01f87e9b..7f3698850d0 100644
--- a/lisp/menu-bar.el
+++ b/lisp/menu-bar.el
@@ -689,7 +689,7 @@ The selected font will be the default on both the existing and future frames."
                    debug-on-quit debug-on-error
                    ;; Somehow this works, when tool-bar and menu-bar don't.
                    tooltip-mode window-divider-mode
-                   save-place uniquify-buffer-name-style fringe-mode
+                   save-place-mode uniquify-buffer-name-style fringe-mode
                    indicate-empty-lines indicate-buffer-boundaries
                    case-fold-search font-use-system-font
                    current-language-environment default-input-method
@@ -1409,7 +1409,7 @@ mail status in mode line"))
 
     (bindings--define-key menu [save-place]
       (menu-bar-make-toggle
-       toggle-save-place-globally save-place
+       toggle-save-place-globally save-place-mode
        "Save Place in Files between Sessions"
        "Saving place in files %s"
        "Visit files of previous session when restarting Emacs"
@@ -1417,7 +1417,7 @@ mail status in mode line"))
        ;; Do it by name, to avoid a free-variable
        ;; warning during byte compilation.
        (set-default
-        'save-place (not (symbol-value 'save-place)))))
+        'save-place-mode (not (symbol-value 'save-place-mode)))))
 
     (bindings--define-key menu [uniquify]
       (menu-bar-make-toggle
diff --git a/lisp/mouse.el b/lisp/mouse.el
index d5c132f484e..cb63ca51c54 100644
--- a/lisp/mouse.el
+++ b/lisp/mouse.el
@@ -327,7 +327,7 @@ This command must be bound to a mouse click."
 (define-obsolete-function-alias 'mouse-tear-off-window 'tear-off-window "24.4")
 (defun tear-off-window (click)
   "Delete the selected window, and create a new frame displaying its buffer."
-  (interactive "e")
+  (interactive (list last-nonmenu-event))
   (mouse-minibuffer-check click)
   (let* ((window (posn-window (event-start click)))
          (buf (window-buffer window))
diff --git a/lisp/net/dbus.el b/lisp/net/dbus.el
index 2d9660d127f..4397817032f 100644
--- a/lisp/net/dbus.el
+++ b/lisp/net/dbus.el
@@ -1798,10 +1798,11 @@ GTK+.  It should be used with care for at least the `:system' and
 this connection to those buses."
   (or (featurep 'dbusbind)
       (signal 'dbus-error (list "Emacs not compiled with dbus support")))
-  (dbus--init-bus bus private)
-  (dbus-register-signal
-   bus nil dbus-path-local dbus-interface-local
-   "Disconnected" #'dbus-handle-bus-disconnect))
+  (prog1
+      (dbus--init-bus bus private)
+    (dbus-register-signal
+     bus nil dbus-path-local dbus-interface-local
+     "Disconnected" #'dbus-handle-bus-disconnect)))
 
  
 ;; Initialize `:system' and `:session' buses.  This adds their file
diff --git a/lisp/net/shr.el b/lisp/net/shr.el
index bc86fe5a383..7ef1e18a1a0 100644
--- a/lisp/net/shr.el
+++ b/lisp/net/shr.el
@@ -321,9 +321,9 @@ under point instead."
 
 (defun shr-copy-url (url)
   "Copy the URL under point to the kill ring.
-If IMAGE-URL (the prefix) is non-nil, or there is no link under
-point, but there is an image under point then copy the URL of the
-image under point instead."
+With a prefix argument, or if there is no link under point, but
+there is an image under point then copy the URL of the image
+under point instead."
   (interactive (list (shr-url-at-point current-prefix-arg)))
   (if (not url)
       (message "No URL under point")
diff --git a/lisp/saveplace.el b/lisp/saveplace.el
index 9d3f10ac352..f8f15cabcd1 100644
--- a/lisp/saveplace.el
+++ b/lisp/saveplace.el
@@ -27,7 +27,7 @@
 ;; Automatically save place in files, so that visiting them later
 ;; (even during a different Emacs session) automatically moves point
 ;; to the saved position, when the file is first found.  Uses the
-;; value of buffer-local variable save-place to determine whether to
+;; value of buffer-local variable save-place-mode to determine whether to
 ;; save position or not.
 ;;
 ;; Thanks to Stefan Schoef, who sent a patch with the
@@ -176,7 +176,7 @@ file:
 
 (defun save-place-to-alist ()
   ;; put filename and point in a cons box and then cons that onto the
-  ;; front of the save-place-alist, if save-place is non-nil.
+  ;; front of the save-place-alist, if save-place-mode is non-nil.
   ;; Otherwise, just delete that file from the alist.
   ;; first check to make sure alist has been loaded in from the master
   ;; file.  If not, do so, then feel free to modify the alist.  It
@@ -306,8 +306,8 @@ may have changed) back to `save-place-alist'."
           nil))))
 
 (defun save-places-to-alist ()
-  ;; go through buffer-list, saving places to alist if save-place is
-  ;; non-nil, deleting them from alist if it is nil.
+  ;; go through buffer-list, saving places to alist if save-place-mode
+  ;; is non-nil, deleting them from alist if it is nil.
   (let ((buf-list (buffer-list)))
     (while buf-list
       ;; put this into a save-excursion in case someone is counting on
@@ -332,7 +332,7 @@ may have changed) back to `save-place-alist'."
               (and (integerp (cdr cell))
                    (goto-char (cdr cell))))
           ;; and make sure it will be saved again for later
-          (setq save-place t)))))
+          (setq save-place-mode t)))))
 
 (declare-function dired-goto-file "dired" (file))
 
@@ -357,7 +357,7 @@ may have changed) back to `save-place-alist'."
                ((and (listp (cdr cell)) (assq 'dired-filename (cdr cell)))
                 (dired-goto-file (cdr (assq 'dired-filename (cdr cell)))))))
           ;; and make sure it will be saved again for later
-          (setq save-place t)))))
+          (setq save-place-mode t)))))
 
 (defun save-place-kill-emacs-hook ()
   ;; First update the alist.  This loads the old save-place-file if nec.
diff --git a/lisp/simple.el b/lisp/simple.el
index f0fcbf57562..e41630d4ed1 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -4352,7 +4352,7 @@ ring directly.")
 A non-nil value ensures that Emacs kill operations do not
 irrevocably overwrite existing clipboard text by saving it to the
 `kill-ring' prior to the kill.  Such text can subsequently be
-retrieved via \\[yank] \\[yank-pop]]."
+retrieved via \\[yank] \\[yank-pop]."
   :type 'boolean
   :group 'killing
   :version "23.2")
diff --git a/lisp/window.el b/lisp/window.el
index 76de4207e74..0a42dae6ca8 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -201,7 +201,7 @@ argument replaces this)."
 
 (defmacro with-current-buffer-window (buffer-or-name action quit-function &rest body)
   "Evaluate BODY with a buffer BUFFER-OR-NAME current and show that buffer.
-This construct is like `with-temp-buffer-window' but unlike that
+This construct is like `with-temp-buffer-window' but unlike that,
 makes the buffer specified by BUFFER-OR-NAME current for running
 BODY."
   (declare (debug t))
@@ -224,7 +224,7 @@ BODY."
 
 (defmacro with-displayed-buffer-window (buffer-or-name action quit-function &rest body)
   "Show a buffer BUFFER-OR-NAME and evaluate BODY in that buffer.
-This construct is like `with-current-buffer-window' but unlike that
+This construct is like `with-current-buffer-window' but unlike that,
 displays the buffer specified by BUFFER-OR-NAME before running BODY."
   (declare (debug t))
   (let ((buffer (make-symbol "buffer"))
@@ -992,16 +992,16 @@ and may be called only if no window on SIDE exists yet."
 ALIST is an association list of symbols and values.  The
 following special symbols can be used in ALIST.
 
-`side' denotes the side of the frame where the new window shall
-  be located.  Valid values are `bottom', `right', `top' and
-  `left'.  The default is `bottom'.
+ `side' denotes the side of the frame where the new window shall
+   be located.  Valid values are `bottom', `right', `top' and
+   `left'.  The default is `bottom'.
 
-`slot' if non-nil, specifies the window slot where to display
-  BUFFER.  A value of zero or nil means use the middle slot on
-  the specified side.  A negative value means use a slot
-  preceding (that is, above or on the left of) the middle slot.
-  A positive value means use a slot following (that is, below or
-  on the right of) the middle slot.  The default is zero.
+ `slot' if non-nil, specifies the window slot where to display
+   BUFFER.  A value of zero or nil means use the middle slot on
+   the specified side.  A negative value means use a slot
+   preceding (that is, above or on the left of) the middle slot.
+   A positive value means use a slot following (that is, below or
+   on the right of) the middle slot.  The default is zero.
 
 If the current frame size or the settings of `window-sides-slots'
 do not permit making a new window, a suitable existing window may
@@ -6384,7 +6384,7 @@ See also `same-window-buffer-names'."
   :group 'windows)
 
 (defun same-window-p (buffer-name)
-  "Return non-nil if a buffer named BUFFER-NAME would be shown in the \"same\" window.
+  "Return non-nil if buffer BUFFER-NAME would be shown in the \"same\" window.
 This function returns non-nil if `display-buffer' or
 `pop-to-buffer' would show a buffer named BUFFER-NAME in the
 selected rather than (as usual) some other window.  See
@@ -6822,16 +6822,22 @@ The actual non-nil value of this variable will be copied to the
   "Custom type for `display-buffer' actions.")
 
 (defvar display-buffer-overriding-action '(nil . nil)
-  "Overriding action to perform to display a buffer.
-It should be a cons cell (FUNCTION . ALIST), where FUNCTION is a
-function or a list of functions.  Each function should accept two
-arguments: a buffer to display and an alist similar to ALIST.
+  "User-defined overriding action to perform to display a buffer.
+This action overrides all the other actions in the action variables
+and arguments passed to `display-buffer'.
+Value should be a cons cell (FUNCTION . ALIST), where FUNCTION is
+a function or a list of functions.  Each function should accept
+two arguments: a buffer to display and an alist similar to ALIST.
+The default value is empty.
 See `display-buffer' for details.")
 (put 'display-buffer-overriding-action 'risky-local-variable t)
 
 (defcustom display-buffer-alist nil
-  "Alist of conditional actions for `display-buffer'.
-This is a list of elements (CONDITION . ACTION), where:
+  "Alist of uder-defined conditional actions for `display-buffer'.
+Its value takes effect before `display-buffer-base-action'
+and `display-buffer-fallback-action', but after
+`display-buffer-overriding-action', which see.
+If non-nil, this is a list of elements (CONDITION . ACTION), where:
 
  CONDITION is either a regexp matching buffer names, or a
   function that takes two arguments - a buffer name and the
@@ -6857,9 +6863,13 @@ associated action to the list of actions it will try."
 
 (defcustom display-buffer-base-action '(nil . nil)
   "User-specified default action for `display-buffer'.
+This is the default action used by `display-buffer' if no other
+actions are specified or all fail, before falling back on
+`display-buffer-fallback-action'.
 It should be a cons cell (FUNCTION . ALIST), where FUNCTION is a
 function or a list of functions.  Each function should accept two
 arguments: a buffer to display and an alist similar to ALIST.
+The default value is empty.
 See `display-buffer' for details."
   :type display-buffer--action-custom-type
   :risky t
@@ -6877,12 +6887,16 @@ See `display-buffer' for details."
   "Default fallback action for `display-buffer'.
 This is the action used by `display-buffer' if no other actions
 specified, e.g. by the user options `display-buffer-alist' or
-`display-buffer-base-action'.  See `display-buffer'.")
+`display-buffer-base-action', or they all fail.  See `display-buffer'.")
 (put 'display-buffer-fallback-action 'risky-local-variable t)
 
 (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'."
+This returns the cdr of the ALIST entry if either its key is a
+string that matches BUFFER-NAME, as reported by `string-match-p';
+or if the key is a function that returns a non-nil when called
+with 3 arguments: the ALIST key, BUFFER-NAME, and ACTION.
+ACTION should have the form of the action argument passed to `display-buffer'."
   (catch 'match
     (dolist (entry alist)
       (let ((key (car entry)))
@@ -6895,7 +6909,8 @@ ACTION is the action argument passed to `display-buffer'."
 (defvar display-buffer--same-window-action
   '(display-buffer-same-window
     (inhibit-same-window . nil))
-  "A `display-buffer' action for displaying in the same window.")
+  "A `display-buffer' action for displaying in the same window.
+Specifies to call `display-buffer-same-window'.")
 (put 'display-buffer--same-window-action 'risky-local-variable t)
 
 (defvar display-buffer--other-frame-action
@@ -6903,7 +6918,9 @@ ACTION is the action argument passed to `display-buffer'."
      display-buffer-pop-up-frame)
     (reusable-frames . 0)
     (inhibit-same-window . t))
-  "A `display-buffer' action for displaying in another frame.")
+  "A `display-buffer' action for displaying in another frame.
+Specifies to call `display-buffer-reuse-window', and if that
+fails, call `display-buffer-pop-up-frame'.")
 (put 'display-buffer--other-frame-action 'risky-local-variable t)
 
 (defun display-buffer (buffer-or-name &optional action frame)
@@ -6924,7 +6941,7 @@ If ACTION is non-nil, it should have the form (FUNCTION . ALIST),
 where FUNCTION is either a function or a list of functions, and
 ALIST is an arbitrary association list (alist).
 
-Each such FUNCTION should accept two arguments: the buffer to
+Each such function should accept two arguments: the buffer to
 display and an alist.  Based on those arguments, it should
 display the buffer and return the window.  If the caller is
 prepared to handle the case of not displaying the buffer
@@ -7048,6 +7065,9 @@ argument, ACTION is t."
 
 (defun display-buffer-other-frame (buffer)
   "Display buffer BUFFER preferably in another frame.
+This function attempts to look for a window displaying BUFFER,
+on all the frames on the current terminal, skipping the selected
+window; if that fails, it pops up a new frame.
 This uses the function `display-buffer' as a subroutine; see
 its documentation for additional customization information."
   (interactive "BDisplay buffer in other frame: ")
@@ -7091,10 +7111,10 @@ that allows the selected frame)."
 
 (defun display-buffer-same-window (buffer alist)
   "Display BUFFER in the selected window.
-This fails if ALIST has a non-nil `inhibit-same-window' entry, or
-if the selected window is a minibuffer window or is dedicated to
-another buffer; in that case, return nil.  Otherwise, return the
-selected window."
+This fails if ALIST has an `inhibit-same-window' element whose
+value is non-nil, or if the selected window is a minibuffer
+window or is dedicated to another buffer; in that case, return nil.
+Otherwise, return the selected window."
   (unless (or (cdr (assq 'inhibit-same-window alist))
               (window-minibuffer-p)
               (window-dedicated-p))
@@ -7581,7 +7601,12 @@ Optional argument NORECORD, if non-nil means do not put this
 buffer at the front of the list of recently selected ones.
 
 Unlike `pop-to-buffer', this function prefers using the selected
-window over popping up a new window or frame."
+window over popping up a new window or frame.  Specifically, if
+the selected window is neither a minibuffer window (as reported
+by `window-minibuffer-p'), nor is dedicated to another buffer
+(see `window-dedicated-p'), BUFFER will be displayed in the
+currently selected window; otherwise it will be displayed in
+another window."
   (pop-to-buffer buffer display-buffer--same-window-action norecord))
 
 (defun read-buffer-to-switch (prompt)
diff --git a/src/keymap.c b/src/keymap.c
index 22e24b2cb00..3a79bf4c5aa 100644
--- a/src/keymap.c
+++ b/src/keymap.c
@@ -2298,7 +2298,7 @@ DEFUN ("text-char-description", Ftext_char_description, Stext_char_description,
        doc: /* Return the description of CHARACTER in standard Emacs notation.
 CHARACTER must be a valid character code that passes the `characterp' test.
 Control characters turn into "^char", and characters with Meta and other
-modifiers signal an error, as they are not valid characterr codes.
+modifiers signal an error, as they are not valid character codes.
 This differs from `single-key-description' which accepts character events,
 and thus doesn't enforce the `characterp' condition, turns control
 characters into "C-char", and uses the 2**27 bit for Meta.