Merge from origin/emacs-27

05089a4d65 (origin/emacs-27) Tweak wording re constant variables
a1040861f1 Tweak setcar-related wording
751510f865 * lisp/image-mode.el: Add prefix key 's' and reduce depend...
9261a219ec * doc/emacs/windows.texi (Window Convenience): Decribe mor...
e1d42da0d6 Fix mutability glitches reported by Drew Adams
5805df74f5 Improve mutability doc
dca35b31d0 Improve mutability documentation
81e7d7f111 Document that quoting yields constants
5734339f40 * doc/lispref/keymaps.texi (Extended Menu Items, Easy Menu...
14a570afae Remove #' and function quoting from lambda forms in manual
d5ec18c66b * src/regex-emacs.c (re_match_2_internal): Rework comment ...
4df8a61117 Add new node "Image Mode" to Emacs Manual.
d7d5ee6c57 ; Fix a typo in cmdargs.texi (bug#40701)
5e9db48fbe * doc/lispref/display.texi (Customizing Bitmaps): Fix typo.
eebfb72c90 Document constant vs mutable objects better
6c187ed6b0 Improve documentation of 'sort-lines'
52288f4b66 Mention 'spam-stat-process-directory-age' in the documenta...
067b070598 ; Fix some typos and doc issues (bug#40695)

# Conflicts:
#	etc/NEWS

8 files changed, 46 insertions, 28 deletions

diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi
index 9303b0b8dd1..2c131165244 100644
--- a/doc/emacs/cmdargs.texi
+++ b/doc/emacs/cmdargs.texi
@@ -340,7 +340,7 @@ initialization file (@pxref{Resources}).
 @opindex --quick
 Start Emacs with minimum customizations.  This is similar to using
 @samp{-q}, @samp{--no-site-file}, @samp{--no-site-lisp},
-@samp{--no-x-resources}, and @samp{--no-splash} together..
+@samp{--no-x-resources}, and @samp{--no-splash} together.
 
 @item -daemon
 @opindex -daemon
diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi
index fba4389094f..d5144141803 100644
--- a/doc/emacs/dired.texi
+++ b/doc/emacs/dired.texi
@@ -1416,7 +1416,8 @@ C-c}.
 
   Image-Dired is a facility for browsing image files.  It provides viewing
 the images either as thumbnails or in full size, either inside Emacs
-or through an external viewer.
+or through an external viewer.  This is different from Image mode
+(@pxref{Image Mode}) for visiting an image file in the Emacs buffer.
 
 @kindex C-t d @r{(Image-Dired)}
 @findex image-dired-display-thumbs
diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index 6ef4ca63ae7..60f2be9a513 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -455,7 +455,8 @@ File Handling
 * Remote Files::        Accessing files on other machines.
 * Quoted File Names::   Quoting special characters in file names.
 * File Name Cache::     Completion against a list of files you often use.
-* File Conveniences::   Convenience Features for Finding Files.
+* File Conveniences::   Convenience features for finding files.
+* Image Mode::          Viewing image files.
 * Filesets::            Handling sets of files.
 
 Saving Files
diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index a89b16b3f6d..7d57555ce33 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -38,7 +38,8 @@ on file directories.
 * Remote Files::        Accessing files on other machines.
 * Quoted File Names::   Quoting special characters in file names.
 * File Name Cache::     Completion against a list of files you often use.
-* File Conveniences::   Convenience Features for Finding Files.
+* File Conveniences::   Convenience features for finding files.
+* Image Mode::          Viewing image files.
 * Filesets::            Handling sets of files.
 @end menu
 
@@ -2088,8 +2089,7 @@ of the cache with the @code{file-cache-display} command.
 @section Convenience Features for Finding Files
 
   In this section, we introduce some convenient facilities for finding
-recently-opened files, reading file names from a buffer, and viewing
-image files.
+recently-opened files, reading file names from a buffer.
 
 @findex recentf-mode
 @vindex recentf-mode
@@ -2108,6 +2108,9 @@ point.  Partial Completion mode offers other features extending
 @code{find-file}, which can be used with @code{ffap}.
 @xref{Completion Options}.
 
+@node Image Mode
+@section Viewing Image Files
+
 @findex image-mode
 @findex image-toggle-display
 @findex image-next-file
diff --git a/doc/emacs/fixit.texi b/doc/emacs/fixit.texi
index 2c268f14fb7..5046146dda6 100644
--- a/doc/emacs/fixit.texi
+++ b/doc/emacs/fixit.texi
@@ -204,8 +204,8 @@ sentences and paragraphs, respectively.  These commands work like
   A numeric argument to a transpose command serves as a repeat count: it
 tells the transpose command to move the character (or word or
 expression or line) before or containing point across several other
-characters (or words or expressions or lines).  For example, @kbd{C-u
-3 C-t} moves the character before point forward across three other
+characters (or words or expressions or lines).  For example, @w{@kbd{C-u
+3 C-t}} moves the character before point forward across three other
 characters.  It would change @samp{f@point{}oobar} into
 @samp{oobf@point{}ar}.  This is equivalent to repeating @kbd{C-t}
 three times.  @kbd{C-u - 4 M-t} moves the word before point backward
@@ -307,10 +307,10 @@ region; @pxref{Disabled Transient Mark}.)
 @cindex spell-checking the active region
   Similarly, the command @kbd{M-x ispell} performs spell-checking in
 the region if one is active, or in the entire buffer otherwise.  The
-commands @kbd{M-x ispell-buffer} and @kbd{M-x ispell-region}
+commands @w{@kbd{M-x ispell-buffer}} and @w{@kbd{M-x ispell-region}}
 explicitly perform spell-checking on the entire buffer or the region
 respectively.  To check spelling in an email message you are writing,
-use @kbd{M-x ispell-message}; that command checks the whole buffer,
+use @w{@kbd{M-x ispell-message}}; that command checks the whole buffer,
 except for material that is indented or appears to be cited from other
 messages.  @xref{Sending Mail}.
 
@@ -368,8 +368,8 @@ wildcard.
 @item C-g
 @itemx X
 Quit interactive spell-checking, leaving point at the word that was
-being checked.  You can restart checking again afterward with @kbd{C-u
-M-$}.
+being checked.  You can restart checking again afterward with @w{@kbd{C-u
+M-$}}.
 
 @item x
 Quit interactive spell-checking and move point back to where it was
@@ -387,8 +387,8 @@ Show the list of options.
 (@code{ispell-complete-word}) performs in-buffer completion based on
 spelling correction.  Insert the beginning of a word, and then type
 @kbd{M-@key{TAB}}; this shows a list of completions.  (If your
-window manager intercepts @kbd{M-@key{TAB}}, type @kbd{@key{ESC}
-@key{TAB}} or @kbd{C-M-i}.)  Each completion is listed with a digit or
+window manager intercepts @kbd{M-@key{TAB}}, type @w{@kbd{@key{ESC}
+@key{TAB}}} or @kbd{C-M-i}.)  Each completion is listed with a digit or
 character; type that digit or character to choose it.
 
 @cindex @code{ispell} program
@@ -396,7 +396,7 @@ character; type that digit or character to choose it.
   Once started, the spell-checker subprocess continues
 to run, waiting for something to do, so that subsequent spell-checking
 commands complete more quickly.  If you want to get rid of the
-process, use @kbd{M-x ispell-kill-ispell}.  This is not usually
+process, use @w{@kbd{M-x ispell-kill-ispell}}.  This is not usually
 necessary, since the process uses no processor time except when you do
 spelling correction.
 
@@ -409,7 +409,7 @@ the standard dictionary and your personal dictionary.  The standard
 dictionary is specified by the variable @code{ispell-local-dictionary}
 or, if that is @code{nil}, by the variable @code{ispell-dictionary}.
 If both are @code{nil}, the spelling program's default dictionary is
-used.  The command @kbd{M-x ispell-change-dictionary} sets the
+used.  The command @w{@kbd{M-x ispell-change-dictionary}} sets the
 standard dictionary for the buffer and then restarts the subprocess,
 so that it will use a different standard dictionary.  Your personal
 dictionary is specified by the variable
@@ -431,8 +431,8 @@ dictionary.
 @findex flyspell-mode
   Flyspell mode is a minor mode that performs automatic spell-checking
 of the text you type as you type it.  When it finds a word that it
-does not recognize, it highlights that word.  Type @kbd{M-x
-flyspell-mode} to toggle Flyspell mode in the current buffer.  To
+does not recognize, it highlights that word.  Type @w{@kbd{M-x
+flyspell-mode}} to toggle Flyspell mode in the current buffer.  To
 enable Flyspell mode in all text mode buffers, add
 @code{flyspell-mode} to @code{text-mode-hook}.  @xref{Hooks}.  Note
 that, as Flyspell mode needs to check each word across which you move,
@@ -448,14 +448,14 @@ it with @kbd{mouse-2} (@code{flyspell-correct-word}) to display a menu
 of possible corrections and actions.  In addition, @kbd{C-.} or
 @kbd{@key{ESC}-@key{TAB}} (@code{flyspell-auto-correct-word}) will
 propose various successive corrections for the word at point, and
-@kbd{C-c $} (@code{flyspell-correct-word-before-point}) will pop up a
+@w{@kbd{C-c $}} (@code{flyspell-correct-word-before-point}) will pop up a
 menu of possible corrections.  Of course, you can always correct the
 misspelled word by editing it manually in any way you like.
 
 @findex flyspell-prog-mode
   Flyspell Prog mode works just like ordinary Flyspell mode, except
 that it only checks words in comments and string constants.  This
-feature is useful for editing programs.  Type @kbd{M-x
-flyspell-prog-mode} to enable or disable this mode in the current
+feature is useful for editing programs.  Type @w{@kbd{M-x
+flyspell-prog-mode}} to enable or disable this mode in the current
 buffer.  To enable this mode in all programming mode buffers, add
 @code{flyspell-prog-mode} to @code{prog-mode-hook} (@pxref{Hooks}).
diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index 7a583b96bbd..94218424d37 100644
--- a/doc/emacs/frames.texi
+++ b/doc/emacs/frames.texi
@@ -227,8 +227,9 @@ left.  If you'd like to reverse the direction of horizontal scrolling,
 customize the variable @code{mouse-wheel-flip-direction} to a
 non-@code{nil} value.
 
-When the mouse pointer is over an image, scrolling the mouse wheel
-with the @key{Ctrl} modifier scales the image under the mouse pointer.
+When the mouse pointer is over an image in Image mode, @pxref{Image Mode},
+scrolling the mouse wheel with the @key{Ctrl} modifier scales the image
+under the mouse pointer.
 
 
 @node Word and Line Mouse
diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index 294430aa183..a15aa17a66f 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -2883,7 +2883,7 @@ if there is an active region (@pxref{Mark}), the default URL comes
 from the region instead, after removing any whitespace from it.  The
 command then creates a new buffer with the embedded browser showing
 the specified URL.  The buffer is put in the Xwidget-WebKit mode
-(similar to Image mode, @pxref{File Conveniences}), which provides
+(similar to Image mode, @pxref{Image Mode}), which provides
 one-key commands for scrolling the widget, changing its size, and
 reloading it.  Type @w{@kbd{C-h b}} in that buffer to see the key
 bindings.
diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi
index 2e07a98f57d..910ef8fd88d 100644
--- a/doc/emacs/windows.texi
+++ b/doc/emacs/windows.texi
@@ -586,13 +586,25 @@ buffer.  @xref{Follow Mode}.
 @cindex directional window selection
 @findex windmove-right
 @findex windmove-default-keybindings
+@findex windmove-display-default-keybindings
+@findex windmove-delete-default-keybindings
+@findex windmove-swap-states-in-direction
   The Windmove package defines commands for moving directionally
 between neighboring windows in a frame.  @kbd{M-x windmove-right}
 selects the window immediately to the right of the currently selected
-one, and similarly for the left, up, and down
-counterparts.  @w{@kbd{M-x windmove-default-keybindings}} binds these
-commands to @kbd{S-right} etc.; doing so disables shift selection for
-those keys (@pxref{Shift Selection}).
+one, and similarly for the left, up, and down counterparts.
+@w{@kbd{M-x windmove-default-keybindings}} binds these commands to
+@kbd{S-right} etc.; doing so disables shift selection for those keys
+(@pxref{Shift Selection}).  In the same way as keybindings can be
+defined for commands that select windows directionally, you can use
+@w{@kbd{M-x windmove-display-default-keybindings}} to define
+keybindings for commands that specify in what direction to display the
+window for the buffer that the next command is going to display.
+Also there is @w{@kbd{M-x windmove-delete-default-keybindings}} to
+define keybindings for commands that delete windows directionally, and
+@w{@kbd{M-x windmove-swap-states-in-direction}} that define
+keybindings for commands that swap the window contents of the selected
+window with the window in the specified direction.
 
   The command @kbd{M-x compare-windows} lets you compare the text
 shown in different windows.  @xref{Comparing Files}.