[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] master 6aa93b4: Merge from origin/emacs-26
|
From: |
Glenn Morris |
|
Subject: |
[Emacs-diffs] master 6aa93b4: Merge from origin/emacs-26 |
|
Date: |
Fri, 28 Sep 2018 10:54:29 -0400 (EDT) |
branch: master
commit 6aa93b45af9fb3631fb8fb6a04407db4d9a74107
Merge: 2d54710 1908173
Author: Glenn Morris <address@hidden>
Commit: Glenn Morris <address@hidden>
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
---
CONTRIBUTE | 2 +-
doc/emacs/custom.texi | 11 ++++++-
doc/emacs/kmacro.texi | 4 +++
doc/lispref/control.texi | 2 +-
doc/lispref/customize.texi | 11 +++----
doc/lispref/os.texi | 2 +-
doc/man/emacsclient.1 | 2 +-
doc/misc/calc.texi | 2 +-
doc/misc/eshell.texi | 2 +-
doc/misc/gnus.texi | 2 +-
doc/misc/org.texi | 4 +--
doc/misc/reftex.texi | 2 +-
doc/misc/sieve.texi | 2 +-
doc/misc/srecode.texi | 2 +-
doc/misc/tramp.texi | 2 +-
doc/misc/url.texi | 2 +-
doc/misc/vhdl-mode.texi | 2 +-
lisp/files.el | 9 ++++--
lisp/menu-bar.el | 6 ++--
lisp/mouse.el | 2 +-
lisp/net/dbus.el | 9 +++---
lisp/net/shr.el | 6 ++--
lisp/saveplace.el | 12 +++----
lisp/simple.el | 2 +-
lisp/window.el | 81 ++++++++++++++++++++++++++++++----------------
src/keymap.c | 2 +-
26 files changed, 113 insertions(+), 72 deletions(-)
diff --git a/CONTRIBUTE b/CONTRIBUTE
index c4f424c..0b68052 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
address@hidden for functions/commands. For the full list of predefine indices,
see
address@hidden 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 51e36ea..ddde5b22 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 dac41fd..0151c81 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}
address@hidden C-x (
Start defining a keyboard macro
(@code{kmacro-start-macro-or-insert-counter}).
@item @key{F4}
address@hidden 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}
address@hidden C-u C-x (
Re-execute last keyboard macro, then append keys to its definition.
@item C-u C-u @key{F3}
address@hidden 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 8a6cf73..0f7502f 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 b3528b1..1cc7cb6 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.
address@hidden Keywords}. Here is an example, from the library
address@hidden:
address@hidden 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 67b78ae..400e6bb 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 daaacab..5aaa6d1 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 446210e..83807c6 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@:}
address@hidden @: j * @:formula @: 27
@:calc-sel-mul-both-sides@:}
address@hidden @: 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 79aac9b..c19d5e1 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
address@hidden to handle non-process targets.
address@hidden to handle non-process targets.
@item Input redirection is not supported
diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi
index 40cc44a..2f7d840 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
address@hidden gnus-group-prepare-hook
address@hidden 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 3bce0dd..ccb5f88 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 2ea98cf..4367d77 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
address@hidden 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 @address@hidden@}}), RefTeX can
prompt for values. Possible values are:
@example
diff --git a/doc/misc/sieve.texi b/doc/misc/sieve.texi
index 2d290b3..cad3cd8 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 2987f62..7d8416e 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 ca40201..88fa55f 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 a8ac117..eaeae60 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
address@hidden, a string or a function of no arguments that
address@hidden, 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 8fc7510..c0efdbf 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 7efbf05..b8f6c46 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 74e01f8..7f36988 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 d5c132f..cb63ca5 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 2d9660d..4397817 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 bc86fe5..7ef1e18 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 9d3f10a..f8f15ca 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 f0fcbf5..e41630d 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 76de420..0a42dae 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 22e24b2..3a79bf4 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.