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

7 files changed, 23 insertions, 27 deletions

diff --git a/lisp/emacs-lisp/bytecomp.el b/lisp/emacs-lisp/bytecomp.el
index 4f01918bdb9..13b72196565 100644
--- a/lisp/emacs-lisp/bytecomp.el
+++ b/lisp/emacs-lisp/bytecomp.el
@@ -677,7 +677,7 @@ Each element is (INDEX . VALUE)")
 (byte-defop 112  1 byte-current-buffer)
 (byte-defop 113  0 byte-set-buffer)
 (byte-defop 114  0 byte-save-current-buffer
-  "To make a binding to record the current buffer")
+  "to make a binding to record the current buffer")
 (byte-defop 115  0 byte-set-mark-OBSOLETE)
 (byte-defop 116  1 byte-interactive-p-OBSOLETE)
 
diff --git a/lisp/emacs-lisp/checkdoc.el b/lisp/emacs-lisp/checkdoc.el
index b5581aa3fbb..e4b800786cc 100644
--- a/lisp/emacs-lisp/checkdoc.el
+++ b/lisp/emacs-lisp/checkdoc.el
@@ -2134,7 +2134,7 @@ buffer, otherwise stop after the first error."
     (checkdoc-ispell-init)
     (unless checkdoc-spellcheck-documentation-flag
       ;; this happens when (checkdoc-ispell-init) can't start `ispell-program-name'
-      (user-error "No spellchecker installed: check the variable `ispell-program-name'."))
+      (user-error "No spellchecker installed: check the variable `ispell-program-name'"))
     (save-excursion
       (skip-chars-forward "^a-zA-Z")
       (let (word sym case-fold-search err word-beginning word-end)
diff --git a/lisp/emacs-lisp/cl-macs.el b/lisp/emacs-lisp/cl-macs.el
index bb10194a946..4408bb58464 100644
--- a/lisp/emacs-lisp/cl-macs.el
+++ b/lisp/emacs-lisp/cl-macs.el
@@ -767,7 +767,7 @@ The result of the body appears to the compiler as a quoted constant."
   "Eval EXPR and choose among clauses on that value.
 Each clause looks like (KEYLIST BODY...).  EXPR is evaluated and
 compared against each key in each KEYLIST; the corresponding BODY
-is evaluated.  If no clause succeeds, cl-case returns nil.  A
+is evaluated.  If no clause succeeds, this macro returns nil.  A
 single non-nil atom may be used in place of a KEYLIST of one
 atom.  A KEYLIST of t or `otherwise' is allowed only in the final
 clause, and matches if no other keys match.  Key values are
@@ -806,10 +806,10 @@ compared by `eql'.
 
 ;;;###autoload
 (defmacro cl-typecase (expr &rest clauses)
-  "Evals EXPR, chooses among clauses on that value.
+  "Eval EXPR and choose among clauses on that value.
 Each clause looks like (TYPE BODY...).  EXPR is evaluated and, if it
 satisfies TYPE, the corresponding BODY is evaluated.  If no clause succeeds,
-cl-typecase returns nil.  A TYPE of t or `otherwise' is allowed only in the
+this macro returns nil.  A TYPE of t or `otherwise' is allowed only in the
 final clause, and matches if no other keys match.
 \n(fn EXPR (TYPE BODY...)...)"
   (declare (indent 1)
@@ -2701,7 +2701,7 @@ 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.
-- `:type': the type of the field; currently unused.
+- `:type': the type of the field; currently only used for documentation.
 
 \(fn NAME &optional DOCSTRING &rest SLOTS)"
   (declare (doc-string 2) (indent 1)
diff --git a/lisp/emacs-lisp/elp.el b/lisp/emacs-lisp/elp.el
index 7dd3cbd1a21..f68c0faf09d 100644
--- a/lisp/emacs-lisp/elp.el
+++ b/lisp/emacs-lisp/elp.el
@@ -238,7 +238,7 @@ FUNSYM must be a symbol of a defined function."
     ;; The info vector data structure is a 2 element vector.  The 0th
     ;; element is the call-count, i.e. the total number of times this
     ;; function has been entered.  This value is bumped up on entry to
-    ;; the function so that non-local exists are still recorded. TBD:
+    ;; the function so that non-local exits are still recorded. TBD:
     ;; I haven't tested non-local exits at all, so no guarantees.
     ;;
     ;; The 1st element is the total amount of time in seconds that has
diff --git a/lisp/emacs-lisp/generator.el b/lisp/emacs-lisp/generator.el
index 27ed29925b3..ba344eb5150 100644
--- a/lisp/emacs-lisp/generator.el
+++ b/lisp/emacs-lisp/generator.el
@@ -59,7 +59,7 @@
 ;; This raw form of iteration is general, but a bit awkward to use, so
 ;; this library also provides some convenience functions:
 ;;
-;; `iter-do' is like `cl-do', except that instead of walking a list,
+;; `iter-do' is like `dolist', except that instead of walking a list,
 ;; it walks an iterator.  `cl-loop' is also extended with a new
 ;; keyword, `iter-by', that iterates over an iterator.
 ;;
@@ -67,7 +67,7 @@
 ;;; Implementation:
 
 ;;
-;; The internal cps transformation code uses the cps- namespace.
+;; The internal CPS transformation code uses the cps- namespace.
 ;; Iteration functions use the `iter-' namespace.  Generator functions
 ;; are somewhat less efficient than conventional elisp routines,
 ;; although we try to avoid CPS transformation on forms that do not
@@ -89,13 +89,13 @@
   `(gensym (format ,fmt ,@args)))
 
 (defvar cps--dynamic-wrappers '(identity)
-  "List of transformer functions to apply to atomic forms we
-evaluate in CPS context.")
+  "List of functions to apply to atomic forms.
+These are transformer functions applied to atomic forms evaluated
+in CPS context.")
 
 (defconst cps-standard-special-forms
   '(setq setq-default throw interactive)
-  "List of special forms that we treat just like ordinary
-  function applications." )
+  "List of special forms treated just like ordinary function applications." )
 
 (defun cps--trace-funcall (func &rest args)
   (message "%S: args=%S" func args)
@@ -118,17 +118,15 @@ evaluate in CPS context.")
        (error "%s not supported in generators" ,function)))
 
 (defmacro cps--with-value-wrapper (wrapper &rest body)
-  "Continue generating CPS code with an atomic-form wrapper
-to the current stack of such wrappers.  WRAPPER is a function that
-takes a form and returns a wrapped form.
+  "Evaluate BODY with WRAPPER added to the stack of atomic-form wrappers.
+WRAPPER is a function that takes an atomic form and returns a wrapped form.
 
 Whenever we generate an atomic form (i.e., a form that can't
 `iter-yield'), we first (before actually inserting that form in our
 generated code) pass that form through all the transformer
 functions.  We use this facility to wrap forms that can transfer
 control flow non-locally in goo that diverts this control flow to
-the CPS state machinery.
-"
+the CPS state machinery."
   (declare (indent 1))
   `(let ((cps--dynamic-wrappers
           (cons
@@ -153,7 +151,7 @@ DYNAMIC-VAR bound to STATIC-VAR."
      ,@body))
 
 (defun cps--add-state (kind body)
-  "Create a new CPS state with body BODY and return the state's name."
+  "Create a new CPS state of KIND with BODY and return the state's name."
   (declare (indent 1))
   (let ((state (cps--gensym "cps-state-%s-" kind)))
     (push (list state body cps--cleanup-function) cps--states)
@@ -170,14 +168,12 @@ DYNAMIC-VAR bound to STATIC-VAR."
     (and (fboundp handler) handler)))
 
 (defvar cps-inhibit-atomic-optimization nil
-  "When non-nil, always rewrite forms into cps even when they
-don't yield.")
+  "When non-nil, always rewrite forms into CPS even when they don't yield.")
 
 (defvar cps--yield-seen)
 
 (defun cps--atomic-p (form)
-  "Return whether the given form never yields."
-
+  "Return nil if FORM can yield, non-nil otherwise."
   (and (not cps-inhibit-atomic-optimization)
        (let* ((cps--yield-seen))
          (ignore (macroexpand-all
@@ -649,8 +645,8 @@ modified copy."
 (defun iter-yield (value)
   "When used inside a generator, yield control to caller.
 The caller of `iter-next' receives VALUE, and the next call to
-`iter-next' resumes execution at the previous
-`iter-yield' point."
+`iter-next' resumes execution with the form immediately following this
+`iter-yield' call."
   (identity value)
   (error "`iter-yield' used outside a generator"))
 
diff --git a/lisp/emacs-lisp/gv.el b/lisp/emacs-lisp/gv.el
index 3ab49293e90..096036a0ffa 100644
--- a/lisp/emacs-lisp/gv.el
+++ b/lisp/emacs-lisp/gv.el
@@ -38,7 +38,7 @@
 ;;
 ;; Instead, we use here a higher-order approach: instead
 ;; of a 5-tuple, a place-expander returns a function.
-;; If you think about types, the old approach return things of type
+;; If you think about types, the old approach returns things of type
 ;;    {vars: List Var, values: List Exp,
 ;;     stores: List Var, getter: Exp, setter: Exp}
 ;; whereas the new approach returns a function of type
diff --git a/lisp/emacs-lisp/lisp-mode.el b/lisp/emacs-lisp/lisp-mode.el
index 3b0f5493eeb..98c44161ad0 100644
--- a/lisp/emacs-lisp/lisp-mode.el
+++ b/lisp/emacs-lisp/lisp-mode.el
@@ -535,7 +535,7 @@ This will generate compile-time constants from BINDINGS."
 
 ;; Support backtrace mode.
 (defconst lisp-el-font-lock-keywords-for-backtraces lisp-el-font-lock-keywords
-  "Default highlighting from Emacs Lisp mod used in Backtrace mode.")
+  "Default highlighting from Emacs Lisp mode used in Backtrace mode.")
 (defconst lisp-el-font-lock-keywords-for-backtraces-1 lisp-el-font-lock-keywords-1
   "Subdued highlighting from Emacs Lisp mode used in Backtrace mode.")
 (defconst lisp-el-font-lock-keywords-for-backtraces-2