commit 316cc9152faee7577e158f7caf26ce4c9cd5371a (HEAD, refs/remotes/origin/master)
Author: Eli Zaretskii <eliz@gnu.org>
Date:   Sun Aug 22 11:32:26 2021 +0300

    Improve documentation of 'set-keyboard-coding-system'
    
    * doc/lispref/nonascii.texi (Terminal I/O Encoding):
    * doc/emacs/mule.texi (Terminal Coding):
    * lisp/international/mule.el (set-keyboard-coding-system):
    Document that 'set-keyboard-coding-system' has no effect on modern
    MS-Windows systems.  (Bug#15289)

diff --git a/doc/emacs/mule.texi b/doc/emacs/mule.texi
index 22b3677b5b..81aabfb57d 100644
--- a/doc/emacs/mule.texi
+++ b/doc/emacs/mule.texi
@@ -1330,6 +1330,12 @@ You can do this by putting
 @noindent
 in your init file.
 
+@findex w32-set-console-codepage
+  Setting @code{keyboard-coding-system} has no effect on MS-Windows,
+except on old Windows 9X systems, in which case the encoding must
+match the current codepage of the MS-Windows console, which can be
+changed by calling @code{w32-set-console-codepage}.
+
   There is a similarity between using a coding system translation for
 keyboard input, and using an input method: both define sequences of
 keyboard input that translate into single characters.  However, input
diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi
index c22930d624..0cc2b7ea1c 100644
--- a/doc/lispref/nonascii.texi
+++ b/doc/lispref/nonascii.texi
@@ -1988,7 +1988,9 @@ for decoding keyboard input from @var{terminal}.  If
 @var{coding-system} is @code{nil}, that means not to decode keyboard
 input.  If @var{terminal} is a frame, it means that frame's terminal;
 if it is @code{nil}, that means the currently selected frame's
-terminal.  @xref{Multiple Terminals}.
+terminal.  @xref{Multiple Terminals}.  Note that on modern MS-Windows
+systems Emacs always uses Unicode input when decoding keyboard input,
+so the encoding set by this command has no effect on Windows.
 @end deffn
 
 @defun terminal-coding-system &optional terminal
diff --git a/lisp/international/mule.el b/lisp/international/mule.el
index 9cd38afd8b..1a53237f14 100644
--- a/lisp/international/mule.el
+++ b/lisp/international/mule.el
@@ -1380,8 +1380,11 @@ If CODING-SYSTEM is nil or the coding-type of CODING-SYSTEM is
 `raw-text', the decoding of keyboard input is disabled.
 
 TERMINAL may be a terminal object, a frame, or nil for the
-selected frame's terminal.  The setting has no effect on
-graphical terminals."
+selected frame's terminal.
+
+The setting has no effect on graphical terminals.  It also
+has no effect on MS-Windows text-mode terminals, except on
+Windows 9X systems.  For Windows 9X, see also `w32-set-console-codepage'."
   (interactive
    (list (let* ((coding (keyboard-coding-system nil))
 		(default (if (eq (coding-system-type coding) 'raw-text)

commit 8fe536f90dae0d14fa3fe76489e41b10c4a4add0
Author: Glenn Morris <rgm@gnu.org>
Date:   Sat Aug 21 18:28:38 2021 -0700

    * test/lisp/international/ucs-normalize-tests.el: Save 30m on hydra.

diff --git a/test/lisp/international/ucs-normalize-tests.el b/test/lisp/international/ucs-normalize-tests.el
index 51f4ed3a80..2b489dc004 100644
--- a/test/lisp/international/ucs-normalize-tests.el
+++ b/test/lisp/international/ucs-normalize-tests.el
@@ -233,6 +233,7 @@ implementations:
 
 (ert-deftest ucs-normalize-part1 ()
   :tags '(:expensive-test)
+  (skip-unless (not (getenv "EMACS_HYDRA_CI"))) ; SLOW ~ 1800s
   ;; This takes a long time, so make sure we're compiled.
   (dolist (fun '(ucs-normalize-tests--part1-rule2
                  ucs-normalize-tests--rule1-failing-for-partX

commit aa27c42cf910391d87396ffed3d2835417471b46
Author: Stephen Gildea <stepheng+emacs@gildea.com>
Date:   Sat Aug 21 17:25:46 2021 -0700

    mh-x-image-url-sane-p: accept "https" URLs
    
    * lisp/mh-e/mh-xface.el (mh-x-image-url-sane-p): Accept https URLs.
    * test/lisp/mh-e/mh-xface.el: New file, to test mh-x-image-url-sane-p.

diff --git a/lisp/mh-e/mh-xface.el b/lisp/mh-e/mh-xface.el
index d4d5c5c378..bc4cc6ecd7 100644
--- a/lisp/mh-e/mh-xface.el
+++ b/lisp/mh-e/mh-xface.el
@@ -391,10 +391,12 @@ filenames.  In addition, replaces * with %2a. See URL
 (defun mh-x-image-url-sane-p (url)
   "Check if URL is something sensible."
   (let ((len (length url)))
-    (cond ((< len 5) nil)
-          ((not (equal (substring url 0 5) "http:")) nil)
-          ((> len 100) nil)
-          (t t))))
+    (cond ((> len 100) nil)
+          ((and (>= len 5)
+                (equal (substring url 0 5) "http:") t))
+          ((and (>= len 6)
+                (equal (substring url 0 6) "https:") t))
+          (t nil))))
 
 (defun mh-x-image-display (image marker)
   "Display IMAGE at MARKER."
diff --git a/test/lisp/mh-e/mh-xface-tests.el b/test/lisp/mh-e/mh-xface-tests.el
new file mode 100644
index 0000000000..65e3c82ec0
--- /dev/null
+++ b/test/lisp/mh-e/mh-xface-tests.el
@@ -0,0 +1,35 @@
+;;; mh-xface-tests.el --- tests for mh-xface.el -*- lexical-binding: t -*-
+
+;; Copyright (C) 2021 Free Software Foundation, Inc.
+
+;; This file is part of GNU Emacs.
+
+;; GNU Emacs is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; GNU Emacs is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
+
+;;; Code:
+
+(require 'ert)
+(require 'mh-xface)
+
+(ert-deftest mh-x-image-url-sane-p ()
+  "Test that `mh-x-image-url-sane-p' accepts a URL exactly if it is sane."
+  (should (equal (mh-x-image-url-sane-p (concat "http://"
+                                                (make-string 101 ?a)))
+                 nil))                  ;too long
+  (should (equal (mh-x-image-url-sane-p "http") nil)) ;too short
+  (should (equal (mh-x-image-url-sane-p "http:") t))
+  (should (equal (mh-x-image-url-sane-p "https") nil)) ;too short
+  (should (equal (mh-x-image-url-sane-p "https:") t))
+  (should (equal (mh-x-image-url-sane-p "https://www.example.com/me.png") t))
+  (should (equal (mh-x-image-url-sane-p "abcde:") nil)))

commit 5f1ee1f8e6d5c7fe3a189676ed6e4bc07af718b0
Author: Stephen Gildea <stepheng+emacs@gildea.com>
Date:   Sat Aug 21 14:37:54 2021 -0700

    ; MH-E doc: SourceForge repo is no longer current
    
    * doc/misc/mh-e.texi, lisp/mh-e/mh-e.el: Update references to
    SourceForge with current URLs and a note that MH-E development
    no longer occurs in that repository.

diff --git a/doc/misc/mh-e.texi b/doc/misc/mh-e.texi
index a7c1fed29c..d2b81a634d 100644
--- a/doc/misc/mh-e.texi
+++ b/doc/misc/mh-e.texi
@@ -8816,8 +8816,8 @@ hands several times since then. Jim Larus wanted to do something
 similar for GNU Emacs, and ended up completely rewriting it that same
 year. In 1989, Stephen Gildea picked it up and added many
 improvements. Bill Wohler then took over in 2000 and moved its
-development to @uref{https://sourceforge.net/, SourceForge} where it
-lives today.
+development to @uref{https://sourceforge.net/, SourceForge}.
+Since 2016, MH-E development occurs within the Emacs repository.
 
 @menu
 * From Brian Reid::
diff --git a/lisp/mh-e/mh-e.el b/lisp/mh-e/mh-e.el
index 949787a250..375072b9d8 100644
--- a/lisp/mh-e/mh-e.el
+++ b/lisp/mh-e/mh-e.el
@@ -33,7 +33,7 @@
 ;; recommended.
 
 ;; MH (Message Handler) is a powerful mail reader. See
-;; http://rand-mh.sourceforge.net/.
+;; https://rand-mh.sourceforge.io/.
 
 ;; N.B. MH must have been compiled with the MHE compiler flag or several
 ;; features necessary for MH-E will be missing from MH commands, specifically
@@ -82,7 +82,8 @@
 ;; Rewritten for GNU Emacs, James Larus, 1985.
 ;; Modified by Stephen Gildea, 1988.
 ;; Maintenance picked up by Bill Wohler and the
-;; SourceForge Crew <http://mh-e.sourceforge.net/>, 2001.
+;;   SourceForge Crew <https://mh-e.sourceforge.io/>, 2001.
+;; Since 2016, MH-E development occurs within the Emacs repository.
 
 ;;; Code:
 

commit bf61ddec3a77d30c5c1d9a9ff41f407facd017ea
Author: Glenn Morris <rgm@gnu.org>
Date:   Sat Aug 21 12:17:39 2021 -0700

    * test/Makefile.in: Turn off hydra verbose logging for electric-tests.

diff --git a/test/Makefile.in b/test/Makefile.in
index a3412d6b53..7047c24482 100644
--- a/test/Makefile.in
+++ b/test/Makefile.in
@@ -163,7 +163,7 @@ endif
 WRITE_LOG = > $@ 2>&1 || { STAT=$$?; cat $@; exit $$STAT; }
 ## On Hydra or Emba, always show logs for certain problematic tests.
 ifdef EMACS_HYDRA_CI
-lisp/net/tramp-tests.log lisp/electric-tests.log \
+lisp/net/tramp-tests.log \
 : WRITE_LOG = 2>&1 | tee $@
 endif
 ifdef EMACS_EMBA_CI

commit 4f1184271d0ffef616e156ab803bc01f0c787cd7
Author: Glenn Morris <rgm@gnu.org>
Date:   Sat Aug 21 11:46:40 2021 -0700

    * test/lisp/net/tramp-tests.el: Reduce hydra run time by 1 hour.
    
    It's just too slow to run these after every commit.

diff --git a/test/lisp/net/tramp-tests.el b/test/lisp/net/tramp-tests.el
index 3008861f22..ee0601fe20 100644
--- a/test/lisp/net/tramp-tests.el
+++ b/test/lisp/net/tramp-tests.el
@@ -6358,6 +6358,7 @@ This requires restrictions of file name syntax."
 ;; These tests are inspired by Bug#17238.
 (ert-deftest tramp-test41-special-characters ()
   "Check special characters in file names."
+  (skip-unless (not (getenv "EMACS_HYDRA_CI"))) ; SLOW ~ 245s
   (skip-unless (tramp--test-enabled))
   (skip-unless (not (tramp--test-rsync-p)))
   (skip-unless (or (tramp--test-emacs26-p) (not (tramp--test-rclone-p))))
@@ -6368,6 +6369,7 @@ This requires restrictions of file name syntax."
   "Check special characters in file names.
 Use the `stat' command."
   :tags '(:expensive-test)
+  (skip-unless (not (getenv "EMACS_HYDRA_CI"))) ; SLOW ~ 287s
   (skip-unless (tramp--test-enabled))
   (skip-unless (tramp--test-sh-p))
   (skip-unless (not (tramp--test-rsync-p)))
@@ -6386,6 +6388,7 @@ Use the `stat' command."
   "Check special characters in file names.
 Use the `perl' command."
   :tags '(:expensive-test)
+  (skip-unless (not (getenv "EMACS_HYDRA_CI"))) ; SLOW ~ 266s
   (skip-unless (tramp--test-enabled))
   (skip-unless (tramp--test-sh-p))
   (skip-unless (not (tramp--test-rsync-p)))
@@ -6407,6 +6410,7 @@ Use the `perl' command."
   "Check special characters in file names.
 Use the `ls' command."
   :tags '(:expensive-test)
+  (skip-unless (not (getenv "EMACS_HYDRA_CI"))) ; SLOW ~ 287s
   (skip-unless (tramp--test-enabled))
   (skip-unless (tramp--test-sh-p))
   (skip-unless (not (tramp--test-rsync-p)))
@@ -6472,6 +6476,7 @@ Use the `ls' command."
 
 (ert-deftest tramp-test42-utf8 ()
   "Check UTF8 encoding in file names and file contents."
+  (skip-unless (not (getenv "EMACS_HYDRA_CI"))) ; SLOW ~ 620s
   (skip-unless (tramp--test-enabled))
   (skip-unless (not (tramp--test-docker-p)))
   (skip-unless (not (tramp--test-rsync-p)))
@@ -6487,6 +6492,7 @@ Use the `ls' command."
   "Check UTF8 encoding in file names and file contents.
 Use the `stat' command."
   :tags '(:expensive-test)
+  (skip-unless (not (getenv "EMACS_HYDRA_CI"))) ; SLOW ~ 595s
   (skip-unless (tramp--test-enabled))
   (skip-unless (tramp--test-sh-p))
   (skip-unless (not (tramp--test-docker-p)))
@@ -6509,6 +6515,7 @@ Use the `stat' command."
   "Check UTF8 encoding in file names and file contents.
 Use the `perl' command."
   :tags '(:expensive-test)
+  (skip-unless (not (getenv "EMACS_HYDRA_CI"))) ; SLOW ~ 620s
   (skip-unless (tramp--test-enabled))
   (skip-unless (tramp--test-sh-p))
   (skip-unless (not (tramp--test-docker-p)))
@@ -6534,6 +6541,7 @@ Use the `perl' command."
   "Check UTF8 encoding in file names and file contents.
 Use the `ls' command."
   :tags '(:expensive-test)
+  (skip-unless (not (getenv "EMACS_HYDRA_CI"))) ; SLOW ~ 690s
   (skip-unless (tramp--test-enabled))
   (skip-unless (tramp--test-sh-p))
   (skip-unless (not (tramp--test-docker-p)))

commit c28d4c995e7a08b4b403f4215d9ac7ac7728731b
Author: Mattias Engdegård <mattiase@acm.org>
Date:   Sat Aug 21 20:16:41 2021 +0200

    ; Load xref when needed (not all functions are autoloaded)

diff --git a/lisp/progmodes/prog-mode.el b/lisp/progmodes/prog-mode.el
index 3babbdc6b4..f75a3039d3 100644
--- a/lisp/progmodes/prog-mode.el
+++ b/lisp/progmodes/prog-mode.el
@@ -44,6 +44,7 @@
                                 prettify-symbols-mode))
 
 (defun prog-context-menu (menu)
+  (require 'xref)
   (define-key-after menu [prog-separator] menu-bar-separator
     'mark-whole-buffer)
   (define-key-after menu [xref-find-def]

commit 9715feaed43c0efc536c90db53d91bc521ef5e41
Author: Glenn Morris <rgm@gnu.org>
Date:   Sat Aug 21 09:41:16 2021 -0700

    * test/lisp/electric-tests.el: Un-skip c-mode tests on hydra.

diff --git a/test/lisp/electric-tests.el b/test/lisp/electric-tests.el
index c5124aca5e..666de89c53 100644
--- a/test/lisp/electric-tests.el
+++ b/test/lisp/electric-tests.el
@@ -587,7 +587,6 @@ baz\"\""
 ;;; Electric newlines between pairs
 ;;; TODO: better tests
 (ert-deftest electric-pair-open-extra-newline ()
-  (skip-unless (not (getenv "EMACS_HYDRA_CI")))
   (save-electric-modes
     (with-temp-buffer
       (c-mode)
@@ -878,8 +877,6 @@ baz\"\""
       (c-brace-newlines (c-point-syntax)))))
 
 (ert-deftest electric-layout-plainer-c-mode-use-c-style ()
-  ;; FIXME hangs since c4d34d2
-  (skip-unless (not (getenv "EMACS_HYDRA_CI")))
   (ert-with-test-buffer ()
     (plainer-c-mode)
     (electric-layout-local-mode 1)
@@ -893,7 +890,6 @@ baz\"\""
     (should (equal (buffer-string) "int main ()\n{\n  \n}\n"))))
 
 (ert-deftest electric-layout-int-main-kernel-style ()
-  (skip-unless (not (getenv "EMACS_HYDRA_CI")))
   (ert-with-test-buffer ()
     (plainer-c-mode)
     (electric-layout-local-mode 1)
@@ -910,7 +906,6 @@ baz\"\""
 (ert-deftest electric-layout-control-reindentation ()
   "Same as `emacs-lisp-int-main-kernel-style', but checking
 Bug#35254."
-  (skip-unless (not (getenv "EMACS_HYDRA_CI")))
   (ert-with-test-buffer ()
     (plainer-c-mode)
     (electric-layout-local-mode 1)
@@ -929,7 +924,6 @@ Bug#35254."
     (should (equal (buffer-string) "int main () {\n\n  \n}"))))
 
 (ert-deftest electric-modes-int-main-allman-style ()
-  (skip-unless (not (getenv "EMACS_HYDRA_CI")))
   (ert-with-test-buffer ()
     (plainer-c-mode)
     (electric-layout-local-mode 1)
@@ -944,7 +938,6 @@ Bug#35254."
     (should (equal (buffer-string) "int main ()\n{\n  \n}"))))
 
 (ert-deftest electric-pair-mode-newline-between-parens ()
-  (skip-unless (not (getenv "EMACS_HYDRA_CI")))
   (ert-with-test-buffer ()
     (plainer-c-mode)
     (electric-layout-local-mode -1) ;; ensure e-l-m mode is off
@@ -956,7 +949,6 @@ Bug#35254."
     (should (equal (buffer-string) "int main () {\n  \n}"))))
 
 (ert-deftest electric-layout-mode-newline-between-parens-without-e-p-m ()
-  (skip-unless (not (getenv "EMACS_HYDRA_CI")))
   (ert-with-test-buffer ()
     (plainer-c-mode)
     (electric-layout-local-mode 1)
@@ -978,7 +970,6 @@ Bug#35254."
     (should (equal (buffer-string) "int main () {\n  \n}"))))
 
 (ert-deftest electric-layout-mode-newline-between-parens-without-e-p-m-2 ()
-  (skip-unless (not (getenv "EMACS_HYDRA_CI")))
   (ert-with-test-buffer ()
     (plainer-c-mode)
     (electric-layout-local-mode 1)

commit efe30626e605e1b8a8601305d17596a120001640
Author: Lars Ingebrigtsen <larsi@gnus.org>
Date:   Sat Aug 21 17:45:24 2021 +0200

    Fix failures in recent files tests
    
    * test/lisp/files-tests.el (files-tests-buffer-offer-save)
    (files-tests-save-buffers-kill-emacs--asks-to-save-buffers):
    `read-event' is called with arguments.

diff --git a/test/lisp/files-tests.el b/test/lisp/files-tests.el
index 174ec5b074..aa5150b4b7 100644
--- a/test/lisp/files-tests.el
+++ b/test/lisp/files-tests.el
@@ -1749,7 +1749,7 @@ PRED is nil."
              buffers-offer
              save-some-buffers
              ;; Increase counter and answer 'n' when prompted to save a buffer.
-             (('read-event . (lambda () (cl-incf nb-saved-buffers) ?n)))
+             (('read-event . (lambda (&rest _) (cl-incf nb-saved-buffers) ?n)))
              args-res)))))))
 
 (ert-deftest files-tests-save-buffers-kill-emacs--asks-to-save-buffers ()
@@ -1766,7 +1766,7 @@ Prompt users for any modified buffer with `buffer-offer-save' non-nil."
        buffers-offer
        save-buffers-kill-emacs
        ;; Increase counter and answer 'n' when prompted to save a buffer.
-       (('read-event . (lambda () (cl-incf nb-saved-buffers) ?n))
+       (('read-event . (lambda (&rest _) (cl-incf nb-saved-buffers) ?n))
         ('kill-emacs . #'ignore)) ; Do not kill Emacs.
        `((nil nil ,nb-might-save)
          ;; `save-some-buffers-default-predicate' (i.e. the 2nd element) is ignored.

commit a0023661a480bee27521981f7324e8670c7906c7
Author: Lars Ingebrigtsen <larsi@gnus.org>
Date:   Sat Aug 21 16:50:16 2021 +0200

    Clarify cl-defstruct doc string and manual entry somewhat
    
    * doc/misc/cl.texi (Structures): Rename the slot "name" in the
    examples to "first-name", since we're talking about the names of
    slots a lot here, and having a slot with the name "name" makes the
    examples somewhat confusing.
    * lisp/emacs-lisp/cl-macs.el (cl-defstruct): Clarify certain
    things about slots (bug#14278).

diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi
index c89e0e75f8..a6c3c32c0e 100644
--- a/doc/misc/cl.texi
+++ b/doc/misc/cl.texi
@@ -3962,22 +3962,22 @@ In the simplest case, @var{name} and each of the @var{slots}
 are symbols.  For example,
 
 @example
-(cl-defstruct person name age sex)
+(cl-defstruct person first-name age sex)
 @end example
 
 @noindent
-defines a struct type called @code{person} that contains three
-slots.  Given a @code{person} object @var{p}, you can access those
-slots by calling @code{(person-name @var{p})}, @code{(person-age @var{p})},
-and @code{(person-sex @var{p})}.  You can also change these slots by
-using @code{setf} on any of these place forms, for example:
+defines a struct type called @code{person} that contains three slots.
+Given a @code{person} object @var{p}, you can access those slots by
+calling @code{(person-first-name @var{p})}, @code{(person-age
+@var{p})}, and @code{(person-sex @var{p})}.  You can also change these
+slots by using @code{setf} on any of these place forms, for example:
 
 @example
 (cl-incf (person-age birthday-boy))
 @end example
 
 You can create a new @code{person} by calling @code{make-person},
-which takes keyword arguments @code{:name}, @code{:age}, and
+which takes keyword arguments @code{:first-name}, @code{:age}, and
 @code{:sex} to specify the initial values of these slots in the
 new object.  (Omitting any of these arguments leaves the corresponding
 slot ``undefined'', according to the Common Lisp standard; in Emacs
@@ -3989,7 +3989,7 @@ object of the same type whose slots are @code{eq} to those of @var{p}.
 Given any Lisp object @var{x}, @code{(person-p @var{x})} returns
 true if @var{x} is a @code{person}, and false otherwise.
 
-Accessors like @code{person-name} normally check their arguments
+Accessors like @code{person-first-name} normally check their arguments
 (effectively using @code{person-p}) and signal an error if the
 argument is the wrong type.  This check is affected by
 @code{(optimize (safety @dots{}))} declarations.  Safety level 1,
@@ -4002,13 +4002,13 @@ always print a descriptive error message for incorrect inputs.
 @xref{Declarations}.
 
 @example
-(setq dave (make-person :name "Dave" :sex 'male))
+(setq dave (make-person :first-name "Dave" :sex 'male))
      @result{} [cl-struct-person "Dave" nil male]
 (setq other (copy-person dave))
      @result{} [cl-struct-person "Dave" nil male]
 (eq dave other)
      @result{} nil
-(eq (person-name dave) (person-name other))
+(eq (person-first-name dave) (person-first-name other))
      @result{} t
 (person-p dave)
      @result{} t
@@ -4021,7 +4021,7 @@ always print a descriptive error message for incorrect inputs.
 @end example
 
 In general, @var{name} is either a name symbol or a list of a name
-symbol followed by any number of @dfn{struct options}; each @var{slot}
+symbol followed by any number of @dfn{structure options}; each @var{slot}
 is either a slot symbol or a list of the form @samp{(@var{slot-name}
 @var{default-value} @var{slot-options}@dots{})}.  The @var{default-value}
 is a Lisp form that is evaluated any time an instance of the
@@ -4029,7 +4029,7 @@ structure type is created without specifying that slot's value.
 
 @example
 (cl-defstruct person
-     (name nil :read-only t)
+     (first-name nil :read-only t)
      age
      (sex 'unknown))
 @end example
@@ -4062,7 +4062,7 @@ enclosed in lists.)
 (cl-defstruct (person (:constructor create-person)
                       (:type list)
                       :named)
-     name age sex)
+     first-name age sex)
 @end example
 
 The following structure options are recognized.
@@ -4108,12 +4108,12 @@ option.
     (person
      (:constructor nil)   ; no default constructor
      (:constructor new-person
-                   (name sex &optional (age 0)))
-     (:constructor new-hound (&key (name "Rover")
+                   (first-name sex &optional (age 0)))
+     (:constructor new-hound (&key (first-name "Rover")
                                    (dog-years 0)
                               &aux (age (* 7 dog-years))
                                    (sex 'canine))))
-    name age sex)
+    first-name age sex)
 @end example
 
 The first constructor here takes its arguments positionally rather
@@ -4165,16 +4165,16 @@ slot descriptors for slots in the included structure, possibly with
 modified default values.  Borrowing an example from Steele:
 
 @example
-(cl-defstruct person name (age 0) sex)
+(cl-defstruct person first-name (age 0) sex)
         @result{} person
 (cl-defstruct (astronaut (:include person (age 45)))
      helmet-size
      (favorite-beverage 'tang))
         @result{} astronaut
 
-(setq joe (make-person :name "Joe"))
+(setq joe (make-person :first-name "Joe"))
      @result{} [cl-struct-person "Joe" 0 nil]
-(setq buzz (make-astronaut :name "Buzz"))
+(setq buzz (make-astronaut :first-name "Buzz"))
      @result{} [cl-struct-astronaut "Buzz" 45 nil nil tang]
 
 (list (person-p joe) (person-p buzz))
@@ -4182,17 +4182,17 @@ modified default values.  Borrowing an example from Steele:
 (list (astronaut-p joe) (astronaut-p buzz))
      @result{} (nil t)
 
-(person-name buzz)
+(person-first-name buzz)
      @result{} "Buzz"
-(astronaut-name joe)
-     @result{} error: "astronaut-name accessing a non-astronaut"
+(astronaut-first-name joe)
+     @result{} error: "astronaut-first-name accessing a non-astronaut"
 @end example
 
 Thus, if @code{astronaut} is a specialization of @code{person},
 then every @code{astronaut} is also a @code{person} (but not the
 other way around).  Every @code{astronaut} includes all the slots
 of a @code{person}, plus extra slots that are specific to
-astronauts.  Operations that work on people (like @code{person-name})
+astronauts.  Operations that work on people (like @code{person-first-name})
 work on astronauts just like other people.
 
 @item :noinline
@@ -4230,10 +4230,10 @@ records, which are always tagged.  Therefore, @code{:named} is only
 useful in conjunction with @code{:type}.
 
 @example
-(cl-defstruct (person1) name age sex)
-(cl-defstruct (person2 (:type list) :named) name age sex)
-(cl-defstruct (person3 (:type list)) name age sex)
-(cl-defstruct (person4 (:type vector)) name age sex)
+(cl-defstruct (person1) first-name age sex)
+(cl-defstruct (person2 (:type list) :named) first-name age sex)
+(cl-defstruct (person3 (:type list)) first-name age sex)
+(cl-defstruct (person4 (:type vector)) first-name age sex)
 
 (setq p1 (make-person1))
      @result{} #s(person1 nil nil nil)
@@ -4254,10 +4254,10 @@ useful in conjunction with @code{:type}.
 
 Since unnamed structures don't have tags, @code{cl-defstruct} is not
 able to make a useful predicate for recognizing them.  Also,
-accessors like @code{person3-name} will be generated but they
-will not be able to do any type checking.  The @code{person3-name}
+accessors like @code{person3-first-name} will be generated but they
+will not be able to do any type checking.  The @code{person3-first-name}
 function, for example, will simply be a synonym for @code{car} in
-this case.  By contrast, @code{person2-name} is able to verify
+this case.  By contrast, @code{person2-first-name} is able to verify
 that its argument is indeed a @code{person2} object before
 proceeding.
 
diff --git a/lisp/emacs-lisp/cl-macs.el b/lisp/emacs-lisp/cl-macs.el
index 4ef1948b0f..d878af4d84 100644
--- a/lisp/emacs-lisp/cl-macs.el
+++ b/lisp/emacs-lisp/cl-macs.el
@@ -2868,16 +2868,21 @@ in SLOTs.  It defines a `make-NAME' constructor, a `copy-NAME'
 copier, a `NAME-p' predicate, and slot accessors named `NAME-SLOT'.
 You can use the accessors to set the corresponding slots, via `setf'.
 
-NAME may instead take the form (NAME OPTIONS...), where each
-OPTION is either a single keyword or (KEYWORD VALUE) where
-KEYWORD can be one of `:conc-name', `:constructor', `:copier',
-`:predicate', `:type', `:named', `:initial-offset',
-`:print-function', `:noinline', or `:include'.  See Info
-node `(cl)Structures' for the description of the options.
-
-Each SLOT may instead take the form (SNAME SDEFAULT SOPTIONS...), where
-SDEFAULT is the default value of that slot and SOPTIONS are keyword-value
-pairs for that slot.
+NAME is usually a symbol, but may instead take the form (NAME
+OPTIONS...), where each OPTION is either a single keyword
+or (KEYWORD VALUE) where KEYWORD can be one of `:conc-name',
+`:constructor', `:copier', `:predicate', `:type', `:named',
+`:initial-offset', `:print-function', `:noinline', or `:include'.
+See Info node `(cl)Structures' for the description of the
+options.
+
+The first element in SLOTS can be a doc string.
+
+The rest of the elements in SLOTS is a list of SLOT elements,
+each of which should either be a symbol, or take the form (SNAME
+SDEFAULT SOPTIONS...), where SDEFAULT is the default value of
+that slot and SOPTIONS are keyword-value pairs for that slot.
+
 Supported keywords for slots are:
 - `:read-only': If this has a non-nil value, that slot cannot be set via `setf'.
 - `:documentation': this is a docstring describing the slot.

commit 69637fe7a612733177b72479269930562d4ba386
Author: Eli Zaretskii <eliz@gnu.org>
Date:   Sat Aug 21 17:38:27 2021 +0300

    ; * lisp/dired.el (dired-jump): Doc fix.

diff --git a/lisp/dired.el b/lisp/dired.el
index 3789bef0ef..950323f366 100644
--- a/lisp/dired.el
+++ b/lisp/dired.el
@@ -4495,11 +4495,10 @@ Ask means pop up a menu for the user to select one of copy, move or link."
 ;;;###autoload
 (defun dired-jump (&optional other-window file-name)
   "Jump to Dired buffer corresponding to current buffer.
-If in a buffer visiting a file, Dired the current directory and
-move to that file's line.
+If in a buffer visiting a file, Dired that file's directory and
+move to that file's line in the directory listing.
 
-If the current buffer isn't visiting a file, jump to the
-`default-directory' Dired buffer.
+If the current buffer isn't visiting a file, Dired `default-directory'.
 
 If in Dired already, pop up a level and goto old directory's line.
 In case the proper Dired file line cannot be found, refresh the dired

commit 690d1bcc619d774c8afbdb01017603ffe0c6bf2b
Author: Lars Ingebrigtsen <larsi@gnus.org>
Date:   Sat Aug 21 16:28:51 2021 +0200

    Fix perldb doc string
    
    * lisp/progmodes/gud.el (perldb): Fix doc string (bug#14588).

diff --git a/lisp/progmodes/gud.el b/lisp/progmodes/gud.el
index 08814ebcaa..021c5a314c 100644
--- a/lisp/progmodes/gud.el
+++ b/lisp/progmodes/gud.el
@@ -1679,9 +1679,14 @@ into one that invokes an Emacs-enabled debugging session.
 
 ;;;###autoload
 (defun perldb (command-line)
-  "Run perldb on program FILE in buffer *gud-FILE*.
-The directory containing FILE becomes the initial working directory
-and source-file directory for your debugger."
+  "Debug a perl program with gud.
+Interactively, this will prompt you for a command line.
+
+Noninteractively, COMMAND-LINE should be on the form
+\"perl -d perl-file.pl\".
+
+The directory containing the perl program becomes the initial
+working directory and source-file directory for your debugger."
   (interactive
    (list (gud-query-cmdline 'perldb
 			    (concat (or (buffer-file-name) "-e 0") " "))))

commit 7ee5d36008b99358748630631a7525c44d3ee147
Author: Lars Ingebrigtsen <larsi@gnus.org>
Date:   Sat Aug 21 16:20:30 2021 +0200

    Clarify dired-jump doc string
    
    * lisp/dired.el (dired-jump): Make the doc string say what happens
    in buffers not visiting files (bug#14733).

diff --git a/lisp/dired.el b/lisp/dired.el
index 0add0ab388..3789bef0ef 100644
--- a/lisp/dired.el
+++ b/lisp/dired.el
@@ -4495,11 +4495,18 @@ Ask means pop up a menu for the user to select one of copy, move or link."
 ;;;###autoload
 (defun dired-jump (&optional other-window file-name)
   "Jump to Dired buffer corresponding to current buffer.
-If in a file, Dired the current directory and move to file's line.
+If in a buffer visiting a file, Dired the current directory and
+move to that file's line.
+
+If the current buffer isn't visiting a file, jump to the
+`default-directory' Dired buffer.
+
 If in Dired already, pop up a level and goto old directory's line.
 In case the proper Dired file line cannot be found, refresh the dired
 buffer and try again.
+
 When OTHER-WINDOW is non-nil, jump to Dired buffer in other window.
+
 When FILE-NAME is non-nil, jump to its line in Dired.
 Interactively with prefix argument, read FILE-NAME."
   (interactive

commit 28019ccf0ce035f4dd842375594da1380b09e806
Author: Eli Zaretskii <eliz@gnu.org>
Date:   Sat Aug 21 17:15:43 2021 +0300

    ; Fix Texinfo markup of a recent change
    
    * doc/lispintro/emacs-lisp-intro.texi (count-words-in-defun): Fix
    last change.

diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi
index dc182a7a45..7933ebe58c 100644
--- a/doc/lispintro/emacs-lisp-intro.texi
+++ b/doc/lispintro/emacs-lisp-intro.texi
@@ -14651,7 +14651,7 @@ Let's re-use @kbd{C-c =} as a convenient keybinding:
 Now we can try out @code{count-words-defun}: install both
 @code{count-words-in-defun} and @code{count-words-defun}, and set the
 keybinding.  Then copy the following to an Emacs Lisp buffer (like,
-for instance, @samp{*scratch*}), place the cursor within the
+for instance, @file{*scratch*}), place the cursor within the
 definition, and use the @kbd{C-c =} command.
 
 @smallexample

commit 964151570b0acb889765d4e973db2fba229ae59e
Author: Eli Zaretskii <eliz@gnu.org>
Date:   Sat Aug 21 17:13:46 2021 +0300

    ; * src/syntax.c: Remove a stray comment.

diff --git a/src/syntax.c b/src/syntax.c
index 1ef4a71228..adc0da730e 100644
--- a/src/syntax.c
+++ b/src/syntax.c
@@ -17,8 +17,6 @@ GNU General Public License for more details.
 You should have received a copy of the GNU General Public License
 along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.  */
 
-// foo
-
 #include <config.h>
 
 #include "lisp.h"

commit 5da710344392ac59a814b8841d31a562823737f0
Author: Lars Ingebrigtsen <larsi@gnus.org>
Date:   Sat Aug 21 16:07:44 2021 +0200

    Tweak the comment-start-skip example in the manual
    
    * doc/emacs/programs.texi (Options for Comments): Tweak the
    example regexp for comment-start-skip (bug#15006).

diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index fe3ee57ac0..09216c278b 100644
--- a/doc/emacs/programs.texi
+++ b/doc/emacs/programs.texi
@@ -1098,13 +1098,13 @@ match the last comment before point in the buffer, and then does a
 expression that is the value of the variable @code{comment-start-skip}.
 Make sure this regexp does not match the null string.  It may match more
 than the comment starting delimiter in the strictest sense of the word;
-for example, in C mode the value of the variable is
+for example, in C mode the value of the variable could be
 @c This stops M-q from breaking the line inside that @code.
-@code{@w{"\\(//+\\|/\\*+\\)\\s *"}}, which matches extra stars and
-spaces after the @samp{/*} itself, and accepts C++ style comments
-also.  (Note that @samp{\\} is needed in Lisp syntax to include a
-@samp{\} in the string, which is needed to deny the first star its
-special meaning in regexp syntax.  @xref{Regexp Backslash}.)
+@code{@w{"/\\*+[ \t]*\\|//+[ \t]*"}}, which matches extra stars and
+spaces after the @samp{/*} itself, and accepts C++ style (@samp{//})
+comments also.  (Note that @samp{\\} is needed in Lisp syntax to
+include a @samp{\} in the string, which is needed to deny the first
+star its special meaning in regexp syntax.  @xref{Regexp Backslash}.)
 
 @vindex comment-start
 @vindex comment-end
diff --git a/src/syntax.c b/src/syntax.c
index 6cbe0f6855..1ef4a71228 100644
--- a/src/syntax.c
+++ b/src/syntax.c
@@ -17,6 +17,7 @@ GNU General Public License for more details.
 You should have received a copy of the GNU General Public License
 along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.  */
 
+// foo
 
 #include <config.h>
 

commit a6240c823350245734bd35335a0affb41ec86d8a
Author: Lars Ingebrigtsen <larsi@gnus.org>
Date:   Sat Aug 21 15:43:06 2021 +0200

    Clarify how to do the `count-words-in-defun' recipe
    
    * doc/lispintro/emacs-lisp-intro.texi (count-words-in-defun):
    Clarify the recipe (bug#15069).

diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi
index fade4096e3..dc182a7a45 100644
--- a/doc/lispintro/emacs-lisp-intro.texi
+++ b/doc/lispintro/emacs-lisp-intro.texi
@@ -14650,7 +14650,9 @@ Let's re-use @kbd{C-c =} as a convenient keybinding:
 
 Now we can try out @code{count-words-defun}: install both
 @code{count-words-in-defun} and @code{count-words-defun}, and set the
-keybinding, and then place the cursor within the following definition:
+keybinding.  Then copy the following to an Emacs Lisp buffer (like,
+for instance, @samp{*scratch*}), place the cursor within the
+definition, and use the @kbd{C-c =} command.
 
 @smallexample
 @group

commit fda6e6e26f061af073820f076a08cbb96749a403
Author: Eli Zaretskii <eliz@gnu.org>
Date:   Sat Aug 21 16:38:24 2021 +0300

    ; * etc/NEWS: Fix last change.

diff --git a/etc/NEWS b/etc/NEWS
index c3993b74f6..86139100ca 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -3109,7 +3109,7 @@ This is to keep the same behavior as Eshell.
 * Incompatible Lisp Changes in Emacs 28.1
 
 ---
-** 'parse-partial-sexp' now signals an error it TO is smaller than FROM.
+** 'parse-partial-sexp' now signals an error if TO is smaller than FROM.
 Previously this would lead to the function interpreting FROM as TO and
 vice versa, which would be confusing when passing in OLDSTATE, which
 refers to the old state at FROM.

commit cabd22f5c6c2f47b1f6efd627e9e760a31e8f015
Author: Lars Ingebrigtsen <larsi@gnus.org>
Date:   Sat Aug 21 15:24:15 2021 +0200

    Make parse-partial-sexp signal an error if TO is smaller than FROM
    
    * src/syntax.c (Fparse_partial_sexp): Signal an error if TO is
    smaller than FROM (bug#49944).

diff --git a/etc/NEWS b/etc/NEWS
index 02185a6fb4..c3993b74f6 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -3108,6 +3108,12 @@ This is to keep the same behavior as Eshell.
 
 * Incompatible Lisp Changes in Emacs 28.1
 
+---
+** 'parse-partial-sexp' now signals an error it TO is smaller than FROM.
+Previously this would lead to the function interpreting FROM as TO and
+vice versa, which would be confusing when passing in OLDSTATE, which
+refers to the old state at FROM.
+
 +++
 ** 'overlays-in' now handles zero-length overlays slightly differently.
 Previosly, zero-length overlays at the end of the buffer were included
diff --git a/src/syntax.c b/src/syntax.c
index 7bba336744..6cbe0f6855 100644
--- a/src/syntax.c
+++ b/src/syntax.c
@@ -3547,8 +3547,10 @@ DEFUN ("parse-partial-sexp", Fparse_partial_sexp, Sparse_partial_sexp, 2, 6, 0,
        doc: /* Parse Lisp syntax starting at FROM until TO; return status of parse at TO.
 Parsing stops at TO or when certain criteria are met;
  point is set to where parsing stops.
-If fifth arg OLDSTATE is omitted or nil,
- parsing assumes that FROM is the beginning of a function.
+
+If OLDSTATE is omitted or nil, parsing assumes that FROM is the
+ beginning of a function.  If not, OLDSTATE should be the state at
+ FROM.
 
 Value is a list of elements describing final state of parsing:
  0. depth in parens.
@@ -3594,6 +3596,9 @@ Sixth arg COMMENTSTOP non-nil means stop after the start of a comment.
   else
     target = TYPE_MINIMUM (EMACS_INT);	/* We won't reach this depth.  */
 
+  if (XFIXNUM (to) < XFIXNUM (from))
+    error ("End position should be larger than start position.");
+
   validate_region (&from, &to);
   internalize_parse_state (oldstate, &state);
   scan_sexps_forward (&state, XFIXNUM (from), CHAR_TO_BYTE (XFIXNUM (from)),
diff --git a/test/src/syntax-tests.el b/test/src/syntax-tests.el
index e4e3054d37..bd89283dd1 100644
--- a/test/src/syntax-tests.el
+++ b/test/src/syntax-tests.el
@@ -500,4 +500,10 @@ the `parse-partial-sexp's are expected to stop.  See
 (syntax-pps-comments /* 56 76 77 58)
 (syntax-pps-comments /* 60 78 79)
 
+(ert-deftest test-from-to-parse-partial-sexp ()
+  (with-temp-buffer
+    (insert "foo")
+    (should (parse-partial-sexp 1 1))
+    (should-error (parse-partial-sexp 2 1))))
+
 ;;; syntax-tests.el ends here

commit 3de577ad0079ecca815086b5f07403cd8e5701a2
Author: Lars Ingebrigtsen <larsi@gnus.org>
Date:   Sat Aug 21 15:03:21 2021 +0200

    Mention problems with synthetic fonts on macOS
    
    * etc/PROBLEMS: Mention synthetic fonts (bug#18818).

diff --git a/etc/PROBLEMS b/etc/PROBLEMS
index 15e34ea06f..f90418798d 100644
--- a/etc/PROBLEMS
+++ b/etc/PROBLEMS
@@ -2660,6 +2660,16 @@ If you do, please send it to bug-gnu-emacs@gnu.org so we can list it here.
 
 Libxpm is available for macOS as part of the XQuartz project.
 
+** Synthetic fonts on macOS
+
+Synthetic bold looks thinner if the background is darker than the
+foreground and font smoothing is turned on.  In such cases, you can
+turn off synthetic bold for particular fonts and use overstriking
+instead by customizing the variable 'face-ignored-fonts'.  For
+instance, if the problem is with the Monaco font, you could put
+something like the following in your init file:
+
+(push "\\`-[^-]*-monaco-bold-" face-ignored-fonts)
 
 * Build-time problems
 

commit 2837e25cafefea84d39a613b0d809194e0f75af0
Author: Alan Third <alan@idiocy.org>
Date:   Sat Aug 21 13:09:37 2021 +0100

    Fix display bug on macOS (bug#50112)
    
    * src/nsterm.m ([EmacsLayer initWithColorSpace:]): Use the colorspace
    setter.
    ([EmacsLayer setColorSpace:]): Sometimes we seem to get null
    colorspaces, so set a default in this case.
    ([EmacsLayer getContext]): Check whether there's been a surface or
    graphics context allocation failure and log it.

diff --git a/src/nsterm.m b/src/nsterm.m
index ba5d81fb6c..1c1f0c8f23 100644
--- a/src/nsterm.m
+++ b/src/nsterm.m
@@ -9394,7 +9394,7 @@ - (id) initWithColorSpace: (CGColorSpaceRef)cs
   if (self)
     {
       cache = [[NSMutableArray arrayWithCapacity:CACHE_MAX_SIZE] retain];
-      colorSpace = cs;
+      [self setColorSpace:cs];
     }
   else
     {
@@ -9409,7 +9409,10 @@ - (void) setColorSpace: (CGColorSpaceRef)cs
 {
   /* We don't need to clear the cache because the new colorspace will
      be used next time we create a new context.  */
-  colorSpace = cs;
+  if (cs)
+    colorSpace = cs;
+  else
+    colorSpace = CGColorSpaceCreateWithName(kCGColorSpaceGenericRGB);
 }
 
 
@@ -9505,6 +9508,12 @@ - (CGContextRef) getContext
                 (id)kIOSurfacePixelFormat:[NSNumber numberWithUnsignedInt:'BGRA']});
         }
 
+      if (!surface)
+        {
+          NSLog (@"Failed to create IOSurface for frame %@", [self delegate]);
+          return nil;
+        }
+
       IOReturn lockStatus = IOSurfaceLock (surface, 0, nil);
       if (lockStatus != kIOReturnSuccess)
         NSLog (@"Failed to lock surface: %x", lockStatus);
@@ -9522,6 +9531,15 @@ - (CGContextRef) getContext
                                        (kCGImageAlphaPremultipliedFirst
                                         | kCGBitmapByteOrder32Host));
 
+      if (!context)
+        {
+          NSLog (@"Failed to create context for frame %@", [self delegate]);
+          IOSurfaceUnlock (currentSurface, 0, nil);
+          CFRelease (currentSurface);
+          currentSurface = nil;
+          return nil;
+        }
+
       CGContextTranslateCTM(context, 0, IOSurfaceGetHeight (currentSurface));
       CGContextScaleCTM(context, scale, -scale);
     }

commit 5eab7c3f70a048dab708512e8ef8114fbe85992e
Author: Alan Third <alan@idiocy.org>
Date:   Tue Aug 17 20:38:55 2021 +0100

    * configure.ac: Make homebrew check for libgccjit match macports.

diff --git a/configure.ac b/configure.ac
index eff5591543..76f608ffb0 100644
--- a/configure.ac
+++ b/configure.ac
@@ -3822,12 +3822,13 @@ if test "${with_native_compilation}" != "no"; then
 
     # Ensure libgccjit installed by Homebrew can be found.
     if test -n "$BREW"; then
-      BREW_LIBGCCJIT_PREFIX=`$BREW --prefix --installed libgccjit 2>/dev/null`
-      if test "$BREW_LIBGCCJIT_PREFIX"; then
-        brew_libdir=`find ${BREW_LIBGCCJIT_PREFIX}/ -name \*.so \
-                     | sed -e '1!d;s|/[[^/]]*\.so$||'`
-        CFLAGS="$CFLAGS -I${BREW_LIBGCCJIT_PREFIX}/include"
-        LDFLAGS="$LDFLAGS -L${brew_libdir} -I${BREW_LIBGCCJIT_PREFIX}/include"
+      if test -n "`$BREW --prefix --installed libgccjit 2>/dev/null`"; then
+        BREW_LIBGCCJIT_INCLUDE=$(dirname $($BREW ls -v libgccjit | \
+                                              grep libgccjit.h))
+        BREW_LIBGCCJIT_LIB=$(dirname $($BREW ls -v libgccjit| \
+                                          grep libgccjit.so\$))
+        CFLAGS="$CFLAGS -I${BREW_LIBGCCJIT_INCLUDE}"
+        LDFLAGS="$LDFLAGS -L${BREW_LIBGCCJIT_LIB}"
       fi
     fi
 

commit f4159568a1682fe8a659bf68614a31406ffe1817
Author: Mattias Engdegård <mattiase@acm.org>
Date:   Fri Aug 20 21:21:05 2021 +0200

    Remove default "Select" title from NS popup menus (bug#50067)
    
    * src/menu.c (x_popup_menu_1): Remove default "Select" title.
    * src/nsmenu.m (ns_menu_show): Allow title to be absent.

diff --git a/src/menu.c b/src/menu.c
index 3b1d740257..e441d22ea0 100644
--- a/src/menu.c
+++ b/src/menu.c
@@ -1286,10 +1286,6 @@ x_popup_menu_1 (Lisp_Object position, Lisp_Object menu)
       prompt = Fkeymap_prompt (keymap);
       if (!NILP (prompt))
 	title = prompt;
-#ifdef HAVE_NS		/* Is that needed and NS-specific?  --Stef  */
-      else
-	title = build_string ("Select");
-#endif
 
       /* Make that be the pane title of the first pane.  */
       if (!NILP (prompt) && menu_items_n_panes >= 0)
diff --git a/src/nsmenu.m b/src/nsmenu.m
index bb0dd2634d..fe4f825832 100644
--- a/src/nsmenu.m
+++ b/src/nsmenu.m
@@ -959,7 +959,7 @@ - (void)menu:(NSMenu *)menu willHighlightItem:(NSMenuItem *)item
     }
 
   pmenu = [[EmacsMenu alloc] initWithTitle:
-                               [NSString stringWithLispString: title]];
+                   NILP (title) ? @"" : [NSString stringWithLispString: title]];
   [pmenu fillWithWidgetValue: first_wv->contents];
   free_menubar_widget_value_tree (first_wv);
   unbind_to (specpdl_count, Qnil);

commit d6ad208b2cea6cb78ea4427ae4715bc5e6c5c85b
Author: Mattias Engdegård <mattiase@acm.org>
Date:   Sat Aug 21 12:38:40 2021 +0200

    Use overlay arrow to indicate current *xref* selection
    
    * lisp/progmodes/xref.el (xref--set-arrow): New function.
    (xref-show-location-at-point, xref-goto-xref)
    (xref--next-error-function): Call it.
    (xref--show-common-initialize): Remove arrow.

diff --git a/lisp/progmodes/xref.el b/lisp/progmodes/xref.el
index a8bab47ea2..d004a0c32c 100644
--- a/lisp/progmodes/xref.el
+++ b/lisp/progmodes/xref.el
@@ -600,12 +600,19 @@ SELECT is `quit', also quit the *xref* window."
                   (xref--show-pos-in-buf marker buf))))))
     (user-error (message (error-message-string err)))))
 
+(defun xref--set-arrow ()
+  "Set the overlay arrow at the line at point."
+  (setq overlay-arrow-position
+        (set-marker (or overlay-arrow-position (make-marker))
+                    (line-beginning-position))))
+
 (defun xref-show-location-at-point ()
   "Display the source of xref at point in the appropriate window, if any."
   (interactive)
   (let* ((xref (xref--item-at-point))
          (xref--current-item xref))
     (when xref
+      (xref--set-arrow)
       (xref--show-location (xref-item-location xref)))))
 
 (defun xref-next-line-no-show ()
@@ -663,6 +670,7 @@ quit the *xref* buffer."
          (xref (or (xref--item-at-point)
                    (user-error "Choose a reference to visit")))
          (xref--current-item xref))
+    (xref--set-arrow)
     (xref--show-location (xref-item-location xref) (if quit 'quit t))
     (if (fboundp 'next-error-found)
         (next-error-found buffer (current-buffer))
@@ -881,6 +889,7 @@ beginning of the line."
            ;; it gets reset to that window's point from time to time).
            (let ((win (get-buffer-window (current-buffer))))
              (and win (set-window-point win (point))))
+           (xref--set-arrow)
            (let ((xref--current-item xref))
              (xref--show-location (xref-item-location xref) t)))
           (t
@@ -1026,6 +1035,7 @@ Return an alist of the form ((FILENAME . (XREF ...)) ...)."
   (let ((inhibit-read-only t)
         (buffer-undo-list t))
     (erase-buffer)
+    (setq overlay-arrow-position nil)
     (xref--insert-xrefs xref-alist)
     (add-hook 'post-command-hook 'xref--apply-truncation nil t)
     (goto-char (point-min))

commit 6993d45e519ad7504adcf5a00842114ce8b25110
Author: Mattias Engdegård <mattiase@acm.org>
Date:   Fri Aug 20 18:19:43 2021 +0200

    Add "Find References" to context menu (bug#50067)
    
    The new entry appears next to "Find Definition" and like it only
    appears when the context menu was invoked on an identifier.
    
    * lisp/progmodes/prog-mode.el (prog-context-menu): New menu entry.
    * lisp/progmodes/xref.el (xref-find-references-at-mouse): New
    function, analogous to `xref-find-definitions-at-mouse`.

diff --git a/lisp/progmodes/prog-mode.el b/lisp/progmodes/prog-mode.el
index 4f000d6613..3babbdc6b4 100644
--- a/lisp/progmodes/prog-mode.el
+++ b/lisp/progmodes/prog-mode.el
@@ -52,13 +52,21 @@
                            (mouse-set-point last-input-event)
                            (xref-backend-identifier-at-point
                             (xref-find-backend)))
-                :help "Find definition of function or variable")
+                :help "Find definition of identifier")
     'prog-separator)
+  (define-key-after menu [xref-find-ref]
+    '(menu-item "Find References" xref-find-references-at-mouse
+                :visible (save-excursion
+                           (mouse-set-point last-input-event)
+                           (xref-backend-identifier-at-point
+                            (xref-find-backend)))
+                :help "Find references to identifier")
+    'xref-find-def)
   (define-key-after menu [xref-pop]
     '(menu-item "Back Definition" xref-pop-marker-stack
                 :visible (not (xref-marker-stack-empty-p))
                 :help "Back to the position of the last search")
-    'xref-find-def)
+    'xref-find-ref)
   menu)
 
 (defvar prog-mode-map
diff --git a/lisp/progmodes/xref.el b/lisp/progmodes/xref.el
index 32fe6b612b..a8bab47ea2 100644
--- a/lisp/progmodes/xref.el
+++ b/lisp/progmodes/xref.el
@@ -1355,6 +1355,20 @@ This command is intended to be bound to a mouse event."
         (xref-find-definitions identifier)
       (user-error "No identifier here"))))
 
+;;;###autoload
+(defun xref-find-references-at-mouse (event)
+  "Find references to the identifier at or around mouse click.
+This command is intended to be bound to a mouse event."
+  (interactive "e")
+  (let ((identifier
+         (save-excursion
+           (mouse-set-point event)
+           (xref-backend-identifier-at-point (xref-find-backend)))))
+    (if identifier
+        (let ((xref-prompt-for-identifier nil))
+          (xref-find-references identifier))
+      (user-error "No identifier here"))))
+
 (declare-function apropos-parse-pattern "apropos" (pattern))
 
 ;;;###autoload

commit b4830907edb7d499f7e81d53e22fe7793a0febcb
Author: Mattias Engdegård <mattiase@acm.org>
Date:   Sat Aug 21 11:34:32 2021 +0200

    Indicate progress while searching for references in xref
    
    * lisp/progmodes/xref.el (xref-backend-references): Add messages to
    show the user that something is happening instead of silently freezing
    during the frequently long synchronous searches for references.

diff --git a/lisp/progmodes/xref.el b/lisp/progmodes/xref.el
index 90329464f2..32fe6b612b 100644
--- a/lisp/progmodes/xref.el
+++ b/lisp/progmodes/xref.el
@@ -290,7 +290,11 @@ find a search tool; by default, this uses \"find | grep\" in the
 current project's main and external roots."
   (mapcan
    (lambda (dir)
-     (xref-references-in-directory identifier dir))
+     (message "Searching %s..." dir)
+     (redisplay)
+     (prog1
+         (xref-references-in-directory identifier dir)
+       (message "Searching %s... done" dir)))
    (let ((pr (project-current t)))
      (cons
       (xref--project-root pr)

commit 4d6e7700314290d76aae26313daea613ae92b81e
Author: Mattias Engdegård <mattiase@acm.org>
Date:   Sat Aug 21 11:05:57 2021 +0200

    Re-type the :location slot in `xref-match-item` to `xref-location`
    
    * lisp/progmodes/xref.el (xref-match-item): Change type for
    :location from `xref-file-location`, which was likely a mistake,
    to `xref-location`. This allows `xref-make-match` to take
    arguments of any subtype of `xref-location` (bug#50067).

diff --git a/lisp/progmodes/xref.el b/lisp/progmodes/xref.el
index 21f4abfccf..90329464f2 100644
--- a/lisp/progmodes/xref.el
+++ b/lisp/progmodes/xref.el
@@ -233,7 +233,7 @@ LOCATION is an `xref-location'."
   ((summary :type string :initarg :summary
             :reader xref-item-summary)
    (location :initarg :location
-             :type xref-file-location
+             :type xref-location
              :reader xref-item-location)
    (length :initarg :length :reader xref-match-length))
   :comment "A match xref item describes a search result.")

commit 49435be616c14d5080e4147ca05204bea5cb1d4f
Author: Mattias Engdegård <mattiase@acm.org>
Date:   Sat Aug 21 10:59:54 2021 +0200

    Add xref operations to context menu unconditionally
    
    * lisp/progmodes/prog-mode.el (prog-context-menu):
    Add xref operations to the context menu even if xref hasn't been
    loaded yet; the functions involved are autoloaded (bug#50067).

diff --git a/lisp/progmodes/prog-mode.el b/lisp/progmodes/prog-mode.el
index a8b608b018..4f000d6613 100644
--- a/lisp/progmodes/prog-mode.el
+++ b/lisp/progmodes/prog-mode.el
@@ -44,21 +44,21 @@
                                 prettify-symbols-mode))
 
 (defun prog-context-menu (menu)
-  (when (featurep 'xref)
-    (define-key-after menu [prog-separator] menu-bar-separator
-      'mark-whole-buffer)
-    (define-key-after menu [xref-find-def]
-      '(menu-item "Find Definition" xref-find-definitions-at-mouse
-                  :visible (save-excursion
-                             (mouse-set-point last-input-event)
-                             (xref-backend-identifier-at-point (xref-find-backend)))
-                  :help "Find definition of function or variable")
-      'prog-separator)
-    (define-key-after menu [xref-pop]
-      '(menu-item "Back Definition" xref-pop-marker-stack
-                  :visible (not (xref-marker-stack-empty-p))
-                  :help "Back to the position of the last search")
-      'xref-find-def))
+  (define-key-after menu [prog-separator] menu-bar-separator
+    'mark-whole-buffer)
+  (define-key-after menu [xref-find-def]
+    '(menu-item "Find Definition" xref-find-definitions-at-mouse
+                :visible (save-excursion
+                           (mouse-set-point last-input-event)
+                           (xref-backend-identifier-at-point
+                            (xref-find-backend)))
+                :help "Find definition of function or variable")
+    'prog-separator)
+  (define-key-after menu [xref-pop]
+    '(menu-item "Back Definition" xref-pop-marker-stack
+                :visible (not (xref-marker-stack-empty-p))
+                :help "Back to the position of the last search")
+    'xref-find-def)
   menu)
 
 (defvar prog-mode-map

commit 20e32f3c3fee1446768786c04b52cde4ce313e37
Author: Alan Mackenzie <acm@muc.de>
Date:   Sat Aug 21 09:39:31 2021 +0000

    CC Mode: Move a macro to before its first use in a file.
    
    * lisp/progmodes/cc-defs.el (c-benign-error): Move earlier in the file for the
    benefit of c-tnt-chng-cleanup.

diff --git a/lisp/progmodes/cc-defs.el b/lisp/progmodes/cc-defs.el
index 3cb1912b73..fe6ff220ba 100644
--- a/lisp/progmodes/cc-defs.el
+++ b/lisp/progmodes/cc-defs.el
@@ -234,6 +234,14 @@ On XEmacs and older Emacsen, this refontifies that region immediately."
       `(font-lock-flush ,beg ,end)
     `(font-lock-fontify-region ,beg ,end)))
 
+(defmacro c-benign-error (format &rest args)
+  ;; Formats an error message for the echo area and dings, i.e. like
+  ;; `error' but doesn't abort.
+  (declare (debug t))
+  `(progn
+     (message ,format ,@args)
+     (ding)))
+
 (defmacro c-point (position &optional point)
   "Return the value of certain commonly referenced POSITIONs relative to POINT.
 The current point is used if POINT isn't specified.  POSITION can be
@@ -1043,14 +1051,6 @@ be after it."
   '(if c-vsemi-status-unknown-p-fn (funcall c-vsemi-status-unknown-p-fn)))
 
 
-(defmacro c-benign-error (format &rest args)
-  ;; Formats an error message for the echo area and dings, i.e. like
-  ;; `error' but doesn't abort.
-  (declare (debug t))
-  `(progn
-     (message ,format ,@args)
-     (ding)))
-
 (defmacro c-with-syntax-table (table &rest code)
   ;; Temporarily switches to the specified syntax table in a failsafe
   ;; way to execute code.

commit 2dfc2bb9bdc685666f6e78d2d169130e28137406
Author: Basil L. Contovounesios <contovob@tcd.ie>
Date:   Sat Aug 21 10:37:26 2021 +0100

    ; * etc/TODO: Fix typo.

diff --git a/etc/TODO b/etc/TODO
index e199e6b02d..8fe698b0c1 100644
--- a/etc/TODO
+++ b/etc/TODO
@@ -1538,7 +1538,7 @@ cannot represent in Unicode.
 
 *** Performance
 
-**** Make the implementation of markers more eifficient
+**** Make the implementation of markers more efficient
 Markers are implemented as a non-sorted singly linked list of markers.
 This makes them scale badly when thousands of markers are created in a
 buffer for some purpose, because some low-level primitives in Emacs

commit 72e688eacdb5fa8c4f1bc52bdcb304201ce8d2f3
Author: Eli Zaretskii <eliz@gnu.org>
Date:   Sat Aug 21 11:49:56 2021 +0300

    Improve documentation of context menus
    
    * doc/lispref/modes.texi (Major Mode Conventions): Add conventions
    of setting menu-bar menus and context menus for a major mode.
    * doc/emacs/frames.texi (Menu Mouse Clicks): Fix description of
    context menu functionality.

diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index 5b15e6290d..d582d24e76 100644
--- a/doc/emacs/frames.texi
+++ b/doc/emacs/frames.texi
@@ -370,11 +370,18 @@ This menu is for changing the default face within the window's buffer.
 @findex context-menu-mode
 @vindex context-menu-functions
 @kindex Down-mouse-3
-  Some graphical applications use @kbd{mouse-3} for a mode-specific
-menu.  If you prefer @kbd{mouse-3} in Emacs to bring up such a context
-menu instead of running the @code{mouse-save-then-kill} command,
-enable @code{context-menu-mode} and customize the variable
-@code{context-menu-functions}.
+  Many GUI applications use @kbd{mouse-3} to display @dfn{context
+menus}: menus that provide access to various pertinent settings and
+actions for the location and context of the mouse click.  If you
+prefer this in Emacs over the default function of @kbd{mouse-3}, which
+is bound to the @code{mouse-save-then-kill} command (@pxref{Mouse
+Commands}), you can enable the minor mode @code{context-menu-mode}.
+Then Emacs will show context menus when you click @kbd{mouse-3}.  The
+exact contents of these context menus depends on the current major
+mode and the buffer contents around the place where you click the
+mouse.  To customize the contents of the context menu, you can use the
+variable @code{context-menu-functions} (@pxref{Major Mode
+Conventions,,, elisp, The Emacs Lisp Reference Manual}).
 
 @node Mode Line Mouse
 @section Mode Line Mouse Commands
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index d9caeab3bc..951f30fc6f 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -470,6 +470,22 @@ setting up a buffer-local value for the variable
 Each face that the mode defines should, if possible, inherit from an
 existing Emacs face.  @xref{Basic Faces}, and @ref{Faces for Font Lock}.
 
+@item
+Consider adding a mode-specific menu to the menu bar.  This should
+preferably include the most important menu-specific settings and
+commands that will allow users discovering the main features quickly
+and efficiently.
+
+@item
+@cindex context menus, for a major mode
+@vindex context-menu-functions
+Consider adding mode-specific context menus for the mode, to be used
+if and when users activate the @code{context-menu-mode} (@pxref{Menu
+Mouse Clicks,,, emacs, The Emacs Manual}).  To this end, define a
+mode-specific function which builds one or more menus depending on the
+location of the @kbd{mouse-3} click in the buffer, and then add that
+function to the buffer-local value of @code{context-menu-functions}.
+
 @item
 The mode should specify how Imenu should find the definitions or
 sections of a buffer, by setting up a buffer-local value for the