Merge from origin/emacs-31

fff343c332 ; Fix typos in iCalendar macro and recurrence docstrings
912c8e3691 Ensure Tramp backward compatibility
df9b97e516 ; update README for windows binaries
9e37c94079 Read a key sequence instead of a single key in 'map-y-or-...
2755f171fc ; Document new features and update NEWS
13842157d2 ; * etc/NEWS: Presentational fixes and improvements.

# Conflicts:
#	etc/NEWS

admin/nt/dist-build/README-windows-binaries

@@ -21,7 +21,6 @@ Making a link to our copy of the source is NOT sufficient, since we
 might upgrade to a new version while you are still distributing the
 old binaries.
 
-
 Windows Binaries
 ================
 
@@ -62,18 +61,34 @@ intended that these will be updated after that point.
 
 Source for Emacs itself is found in the directory above.
 
+Emacs binaries are normally built using MSYS2/MINGW64 and include a full
+"Ahead of Time" (AOT) build of provided elisp.  Other binaries for a
+given version of Emacs, if any, that have been created from atypical
+compilation environments or built using alternative (e.g. "noaot")
+settings may include architecture (e.g. "i668") and or other "tags"
+following the version identifier (for example:
+emacs-X.Y.Z-i686-notreesitter-nognutls.zip).
+
 Snapshots
 =========
 
 We also distribute "snapshots" of Emacs built at points throughout the
 development cycle, for those interested in following this cycle.  They
 are not recommended for normal users; however, they are useful for
-people who want to report bugs against the current master.
+people who want to report bugs against the current master, to help in
+"pretesting" new release versions, and so on.
 
 The files follow the same naming convention, but also include a date
-(and sometimes information about their branch).  The Emacs source at
+(and sometimes information about their branch) or they may releate to a
-the time of these builds is also distributed.
+sepecific pretest or release candidate for an "uncut" Emacs.  Emacs
+sources are distributed along with each dated snapshot.  Sources are
+provided for the pretest and release candidate Emacs versions here, as
+for release builds, are found in the directory (or directories) above.
 
+Meta
+====
+
+You can find a copy this file, along with other programs used to build Emacs as a native windows program using the MSYS2 toolchain, within the emacs source tree, see: https://git.savannah.gnu.org/cgit/emacs.git/tree/admin/nt/dist-build
 
 LICENSE
 ======

doc/emacs/display.texi

@@ -1640,12 +1640,16 @@ present.
 
 @findex delete-trailing-whitespace
 @vindex delete-trailing-lines
+@findex delete-trailing-whitespace-mode
   Type @kbd{M-x delete-trailing-whitespace} to delete all trailing
 whitespace.  This command deletes all extra spaces at the end of each
 line in the buffer, and all empty lines at the end of the buffer; to
 ignore the latter, change the variable @code{delete-trailing-lines} to
 @code{nil}.  If the region is active, the command instead deletes
-extra spaces at the end of each line in the region.
+extra spaces at the end of each line in the region.  If you enable the
+buffer-local mode @code{delete-trailing-whitespace-mode}, Emacs will
+automatically invoke @code{delete-trailing-whitespace} each time you
+save the buffer.
 
 @vindex indicate-empty-lines
 @cindex unused lines

doc/emacs/frames.texi

@@ -82,6 +82,9 @@ Move point to where you click (@code{mouse-set-point}).
 Activate the region around the text selected by dragging, and put the
 text in the primary selection (@code{mouse-set-region}).
 
+@item S-mouse-1
+Adjust already selected region.
+
 @item mouse-2
 Move point to where you click, and insert the contents of the primary
 selection there (@code{mouse-yank-primary}).
@@ -134,6 +137,12 @@ is less than a half a character, you'd normally get the empty string
 in your kill ring, but with @code{non-empty}, this short mouse drag
 won't affect the kill ring.
 
+@findex mouse-shift-adjust-mode
+  If you activate the Mouse-Shift-Adjust minor mode, clicking the left
+mouse button with the @kbd{Shift} modifier (@kbd{S-down-mouse-1})
+adjusts (extends or shrinks, depending on where you click) the already
+selected region.
+
 @vindex mouse-scroll-min-lines
   If you move the mouse off the top or bottom of the window while
 dragging, the window scrolls at a steady rate until you move the mouse
@@ -1918,6 +1927,7 @@ in the mode line when the frame is selected.
 Some text terminals support mouse clicks in the terminal window.
 
 @cindex xterm
+@findex xterm-mouse-mode
   In a terminal emulator which is compatible with @command{xterm}, you
 can use @kbd{M-x xterm-mouse-mode} to give Emacs control over simple
 uses of the mouse---basically, only non-modified single clicks are
@@ -1925,8 +1935,9 @@ supported.  Newer versions of @command{xterm} also support
 mouse-tracking.  The normal @command{xterm} mouse functionality for
 such clicks is still available by holding down the @key{SHIFT} key
 when you press the mouse button.  Xterm Mouse mode is a global minor
-mode (@pxref{Minor Modes}).  Repeating the command turns the mode off
+mode (@pxref{Minor Modes}), which is turned on by default if Emacs
-again.
+detects at start time that the terminal supports it.  Repeating the
+command turns the mode off again.
 
 @findex gpm-mouse-mode
   In the console on GNU/Linux, you can use @kbd{M-x gpm-mouse-mode} to

doc/emacs/search.texi

@@ -1937,6 +1937,10 @@ case.  I.e., if you have a @code{query-replace} from @samp{foo} to
 @samp{Bar}.  Use this command to do the current replacement with exact
 case.
 
+@item d
+to show the replacement of the current match as a buffer of diffs
+between the original text and text with the match replaced.
+
 @item C-l
 to redisplay the screen.  Then you must type another character to
 specify what to do with this occurrence.

doc/emacs/text.texi

@@ -1408,7 +1408,8 @@ particular chapter or section of your document.
 This hides all the text and subheadings under the top-level heading and
 returns you to the previous view of the buffer.  Specifying a numeric
 argument exits that many levels of folds.  Specifying a zero argument
-exits all folds.
+exits all folds.  Specifying a negative argument (so that the exited
+fold remains visible) preserves the position of point and window view.
 
   To cancel the narrowing of a fold without hiding the text and
 subheadings, specify a negative argument.  For example, @w{@kbd{M--2 C-c

doc/lispref/commands.texi

@@ -3777,14 +3777,15 @@ supplied to input methods (@pxref{Input Methods}).  Use
 if you want to translate characters after input methods operate.
 @end defvar
 
-@defun key-translate from to
+@deffn Command key-translate from to
-This function modifies @code{keyboard-translate-table} to translate
+This command modifies @code{keyboard-translate-table} to translate
-character code @var{from} into character code @var{to}.  It creates the
+character code @var{from} into character code @var{to}.  Interactively,
+it prompts for @var{from} and @var{to}.  It creates the
 keyboard translate table if necessary.  Both @var{from} and @var{to}
 should be strings that satisfy @code{key-valid-p} (@pxref{Key
 Sequences}).  If @var{to} is @code{nil}, the function removes any
 existing translation for @var{from}.
-@end defun
+@end deffn
 
   Here's an example of using the @code{keyboard-translate-table} to
 make @kbd{C-x}, @kbd{C-c} and @kbd{C-v} perform the cut, copy and paste
@@ -3812,6 +3813,12 @@ input events that are not characters (i.e., @code{characterp} returns
 @code{nil} for them), you must use the event translation mechanism
 described there.
 
+@deffn Command key-translate-remove from
+This command prompts for a key @var{from} and its translation, and
+removes the translation from the translation table.  When calling from
+Lisp, specify just the key @var{from}, without its translation.
+@end deffn
+
 @node Invoking the Input Method
 @subsection Invoking the Input Method
 @cindex invoking input method

doc/lispref/frames.texi

@@ -1303,6 +1303,28 @@ The default is @code{inhibit} on NS builds and @code{nil} everywhere
 else.
 @end defopt
 
+@defun set-frame-size-and-position &optional frame width height left top
+This function sets the new size and position of @var{frame} in a single
+step; @var{frame} defaults to the selected frame.  The size and position
+are specified as with the corresponding frame parameters @code{width},
+@code{height}, @code{left}, and @code{top} (@pxref{Size Parameters}, and
+@pxref{Position Parameters}).  If any of these 4 arguments is omitted or
+@code{nil}, that means not to change the corresponding parameter of
+@var{frame}.
+@end defun
+
+@cindex gravity of frame
+@defun set-frame-size-and-position-pixelwise frame width height x y &optional gravity
+This function sets the new size and position of a frame, similarly to
+@code{set-frame-size-and-position}, but in pixel units.  The optional
+argument @var{gravity} specified the new @dfn{gravity} of a frame and
+must be a value between 0 and 10; it defaults to 1.  The gravity
+determines how a window or its contents adjust when resized or
+positioned.  The interpretation is specific to each window-system; for
+example, GTK uses window gravity to define which point of the window
+remains fixed during resizing.
+@end defun
+
 @cindex tracking frame size changes
   The abnormal hook @code{window-size-change-functions} (@pxref{Window
 Hooks}) tracks all changes of the inner size of a frame including those

doc/lispref/minibuf.texi

@@ -2380,9 +2380,12 @@ asking each question individually.  This gives the user certain
 convenient facilities such as the ability to answer the whole series at
 once.
 
+@vindex y-or-n-p-use-read-key@r{, and} map-y-or-n-p
 @defun map-y-or-n-p prompter actor list &optional help action-alist no-cursor-in-echo-area
 This function asks the user a series of questions, reading a
-single-character answer in the echo area for each one.
+single-character answer in the minibuffer for each one.  However, if
+@code{y-or-n-p-use-read-key} is non-@code{nil} (@pxref{Key Sequence
+Input}), it reads a key sequence from the echo area.
 
 The value of @var{list} specifies the objects to ask questions about.
 It should be either a list of objects or a generator function.  If it

doc/lispref/processes.texi

@@ -1670,9 +1670,10 @@ On some systems, when Emacs reads the output from a subprocess, the
 output data is read in very small blocks, potentially resulting in
 very poor performance.  This behavior can be remedied to some extent
 by setting the variable @code{process-adaptive-read-buffering} to a
-non-@code{nil} value (the default), as it will automatically delay reading
+non-@code{nil} value, as it will automatically delay reading
 from such processes, thus allowing them to produce more output before
-Emacs tries to read it.
+Emacs tries to read it.  The default is @code{nil}, since a
+non-@code{nil} value reduces performance.
 @end defvar
 
 @menu

lisp/calendar/icalendar-macs.el

@@ -989,7 +989,7 @@ Each binding in BINDINGS should be a list of one of the following forms:
   "Execute BODY with bindings in BINDINGS taken from NODE and its children.
 
 NODE should be an iCalendar syntax node representing a property or
-parameter.  If NODE is not a syntax node, this form evalutes to nil
+parameter.  If NODE is not a syntax node, this form evaluates to nil
 without binding the variables in BINDINGS and without executing BODY.
 
 Within BODY, if NODE's value is itself a syntax node, the symbol
@@ -1044,7 +1044,7 @@ available in BODY; see its docstring for their form."
     "Execute BODY with BINDINGS taken from the value and parameters in NODE.
 
 NODE should be an iCalendar syntax node representing a property.  If NODE
-is not a syntax node, this form evalutes to nil without binding the
+is not a syntax node, this form evaluates to nil without binding the
 variables in BINDINGS and without executing BODY.
 
 Within BODY, if NODE's value is itself a syntax node, the symbol
@@ -1067,7 +1067,7 @@ available in BODY; see its docstring for their form.")
   "Bind the value in PARAMETER and execute BODY.
 
 PARAMETER should be an iCalendar syntax node representing a
-parameter.  If PARAMETER is nil, this form evalutes to nil without
+parameter.  If PARAMETER is nil, this form evaluates to nil without
 executing BODY.
 
 Within BODY, if PARAMETER's value is a syntax node, the symbol
@@ -1087,7 +1087,7 @@ bound to nil."
 
 Find the first child node of type TYPE in NODE, bind that
 child node's value and any of its children in BINDINGS and execute BODY
-with these bindings.  If there is no such node, this form evalutes to
+with these bindings.  If there is no such node, this form evaluates to
 nil without executing BODY.
 
 Within BODY, the symbols `value-node', `value-type', and `value' will be

lisp/calendar/icalendar-recur.el

@@ -1644,7 +1644,7 @@ with the UTC offset in effect prior to the OBS-ONSET of OBSERVANCE (see
 RFC5545 Section 3.3.5).  So e.g. at the switch from Standard to Daylight
 in US Eastern, 2:30AM EST (a nonexistent time) becomes 3:30AM EDT, and
 at the switch from Daylight to Standard, 1:30AM (which occurs twice)
-becomes 1:30AM EDT, the first occurence."
+becomes 1:30AM EDT, the first occurrence."
   (ical:with-component observance
       ((ical:tzoffsetfrom :value offset-from)
        (ical:tzoffsetto :value offset-to))

lisp/emacs-lisp/map-ynp.el

@@ -105,7 +105,7 @@ function is used instead.
 The function's value is the number of actions taken."
   (let* ((actions 0)
          (msg (current-message))
-	 user-keys mouse-event map prompt char elt def
+	 user-keys mouse-event map prompt chars elt def
 	 ;; Non-nil means we should use mouse menus to ask.
 	 use-menus
 	 delayed-switch-frame
@@ -174,14 +174,15 @@ The function's value is the number of actions taken."
 				   'quit)))
 		    (y-or-n-p-use-read-key
 		     ;; Prompt in the echo area using `read-key'.
-		     (let ((cursor-in-echo-area (not no-cursor-in-echo-area)))
+		     (let ((cursor-in-echo-area (not no-cursor-in-echo-area))
-                       (message "%s" (substitute-command-keys
+                           (full-prompt
+                            (substitute-command-keys
                              (format
                               (apply #'propertize
                                      "%s(\\`y', \\`n', \\`!', \\`.', \\`q', %sor \\`%s') "
                                      minibuffer-prompt-properties)
                               prompt user-keys
-                                      (help-key))))
+                              (help-key)))))
 		       (if minibuffer-auto-raise
 			   (raise-frame (window-frame (minibuffer-window))))
                        (unwind-protect
@@ -196,8 +197,8 @@ The function's value is the number of actions taken."
                              ;; Do NOT use read-event here.  That
                              ;; function does not consult
                              ;; input-decode-map (bug#75886).
-		             (setq char (read-key))
+		             (setq chars (read-key-sequence-vector full-prompt))
-                             (when (eq char ?\C-g)
+                             (when (member chars '([?\C-g] [?\C-\[ ?\C-\[ ?\C-\[]))
                                (signal 'quit nil)))
                          (when (fboundp 'set-text-conversion-style)
                            (set-text-conversion-style text-conversion-style)))
@@ -207,10 +208,10 @@ The function's value is the number of actions taken."
                                        "%s(\\`y', \\`n', \\`!', \\`.', \\`q', %sor \\`%s') %s"
                                        prompt user-keys
                                        (help-key)
-                                       (if (equal char -1)
+                                       (if (equal chars [-1])
                                            "[end-of-keyboard-macro]"
-                                         (single-key-description char))))))
+                                         (key-description chars))))))
-		     (setq def (lookup-key map (vector char))))
+		     (setq def (and chars (lookup-key map chars))))
                     (t
                      ;; Read from the minibuffer.
                      (let* ((full-prompt
@@ -224,7 +225,7 @@ The function's value is the number of actions taken."
                             (cmd-char
                              (lambda ()
                                (interactive)
-                               (setq char last-command-event)
+                               (setq chars (this-command-keys-vector))
                                (exit-minibuffer)))
                             (cmd-help
                              (lambda ()
@@ -250,8 +251,8 @@ The function's value is the number of actions taken."
                        (read-from-minibuffer
                         full-prompt nil remap nil
                         (or y-or-n-p-history-variable t))
-                       (message "%s%s" full-prompt (single-key-description char)))
+                       (message "%s%s" full-prompt (key-description chars)))
-                     (setq def (lookup-key map (vector char)))))
+                     (setq def (and chars (lookup-key map chars)))))
                    (cond ((eq def 'exit)
 			  (setq next (lambda () nil)))
 			 ((eq def 'act)
@@ -318,12 +319,16 @@ Type \\`SPC' or \\`y' to %s the current %s;
 			      (setq actions (1+ actions))
 			    ;; Regurgitated; try again.
 			    (funcall try-again)))
-			 ((and (consp char)
+			 ((eq chars '[switch-frame])
-			       (eq (car char) 'switch-frame))
 			  ;; switch-frame event.  Put it off until we're done.
-			  (setq delayed-switch-frame char)
+			  (setq delayed-switch-frame chars)
 			  (funcall try-again))
-			 ((eq def nil) ;; Special case for bug#67836
+			 ((and noninteractive (member chars '(nil [])))
+                          ;; Special case for kmacro in batch mode (bug#67836).
+                          ;; When 'y-or-n-p-use-read-key' is non-nil,
+                          ;; 'read-key-sequence-vector' returns [].
+                          ;; When 'y-or-n-p-use-read-key' is nil,
+                          ;; 'chars' is nil.
 			  (error "Can't use in a kmacro in batch mode"))
 			 (t
 			  ;; Random char.

lisp/net/tramp.el

@@ -5478,8 +5478,10 @@ should be set connection-local.")
   "Return non-nil if ARG exists in default `process-environment'.
 Tramp does not propagate local environment variables in remote
 processes."
-  (or (ignore-error void-variable
+  (or ;; `buffer-local-toplevel-value' has been defined in Emacs 31.1.
-        (member arg (buffer-local-toplevel-value 'process-environment)))
+      (ignore-error (void-variable void-function)
+        (member arg (tramp-compat-funcall 'buffer-local-toplevel-value
+		      'process-environment)))
       (member arg (default-toplevel-value 'process-environment))))
 
 (defun tramp-handle-make-process (&rest args)

test/lisp/emacs-lisp/map-ynp-tests.el

@@ -31,8 +31,7 @@
 (defun map-ynp-tests-simple-call ()
   (map-y-or-n-p ""  #'ignore '(1)))
 
-(ert-deftest test-map-ynp-kmacro ()
+(defun test-map-ynp-kmacro-1 ()
-  "Test that `map-y-or-n-p' in a kmacro terminates on end of input."
   (let ((eval-expression-debug-on-error nil)) ;; bug#67836
     (execute-kbd-macro (read-kbd-macro "M-: (map-ynp-tests-simple-call) RET y"))
     (should-error
@@ -43,5 +42,80 @@
         (should-error
          (execute-kbd-macro (read-kbd-macro "M-: (map-ynp-tests-simple-call) RET")))))))
 
+(ert-deftest test-map-ynp-kmacro ()
+  "Test that `map-y-or-n-p' in a kmacro terminates on end of input."
+  (let ((y-or-n-p-use-read-key nil))
+    (test-map-ynp-kmacro-1))
+  (let ((y-or-n-p-use-read-key t))
+    (test-map-ynp-kmacro-1)))
+
+(defvar map-ynp-tests-result nil)
+
+(defvar-keymap map-ynp-tests-map
+  "C-x s" 'map-ynp-tests-command)
+
+(defun map-ynp-tests-command-symbol (obj)
+  (interactive)
+  (push obj map-ynp-tests-result))
+
+(defun map-ynp-tests-command ()
+  (interactive)
+  (should (equal (map-y-or-n-p
+                  "Prompt "
+                  (lambda (obj)
+                    (push obj map-ynp-tests-result))
+                  '(1 2 3 4)
+                  nil
+                  `((?\C-r map-ynp-tests-command-symbol "C-r")
+                    (?\M-~ ,(lambda (obj)
+                              (push obj map-ynp-tests-result))
+                           "M-~")))
+                 (length map-ynp-tests-result))))
+
+(defun map-ynp-tests-run (keys result)
+  (setq map-ynp-tests-result nil)
+  (execute-kbd-macro (read-kbd-macro (concat "C-x s " keys)))
+  (should (equal (nreverse map-ynp-tests-result) result)))
+
+(defun test-map-ynp-keys-1 ()
+  (with-temp-buffer
+    (save-window-excursion
+      ;; `execute-kbd-macro' applied to window only
+      (set-window-buffer nil (current-buffer))
+      (use-local-map map-ynp-tests-map)
+
+      (map-ynp-tests-run "y Y SPC n" '(1 2 3))
+      (map-ynp-tests-run "n N DEL y" '(4))
+      (map-ynp-tests-run "n !" '(2 3 4))
+      (map-ynp-tests-run "." '(1))
+      (map-ynp-tests-run "y q" '(1))
+      (map-ynp-tests-run "y RET" '(1))
+      (map-ynp-tests-run "C-r M-~ ESC ~ q" '(1 2 3))
+
+      (map-ynp-tests-run "x q" nil) ;; x - random char
+
+      (kill-buffer (help-buffer))
+      (if y-or-n-p-use-read-key
+          (map-ynp-tests-run "? q" nil)
+        (map-ynp-tests-run "C-h q" nil))
+      (should (get-buffer (help-buffer)))
+
+      (should (equal 'quit
+                     (condition-case err
+                         (map-ynp-tests-run "C-g" nil)
+                       (quit (car err)))))
+
+      (should (equal 'quit
+                     (condition-case err
+                         (map-ynp-tests-run "ESC ESC ESC" nil)
+                       (quit (car err))))))))
+
+(ert-deftest test-map-ynp-keys ()
+  "Test keys for `map-y-or-n-p'."
+  (let ((y-or-n-p-use-read-key nil))
+    (test-map-ynp-keys-1))
+  (let ((y-or-n-p-use-read-key t))
+    (test-map-ynp-keys-1)))
+
 (provide 'map-ynp-tests)
 ;;; map-ynp-tests.el ends here