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

16 files changed, 205 insertions, 126 deletions

diff --git a/doc/lispref/abbrevs.texi b/doc/lispref/abbrevs.texi
index 6689b560c78..575be187d3f 100644
--- a/doc/lispref/abbrevs.texi
+++ b/doc/lispref/abbrevs.texi
@@ -370,9 +370,9 @@ definitions of @code{local-abbrev-table} and @code{text-mode-abbrev-table}.
       (funcall expand))))
 
 (add-hook 'foo-mode-hook
-          #'(lambda ()
-              (add-function :around (local 'abbrev-expand-function)
-                            #'foo-mode-abbrev-expand-function)))
+          (lambda ()
+            (add-function :around (local 'abbrev-expand-function)
+                          #'foo-mode-abbrev-expand-function)))
 @end smallexample
 
 @node Standard Abbrev Tables
diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi
index b7318a99b8f..4ed1a10fcf6 100644
--- a/doc/lispref/backups.texi
+++ b/doc/lispref/backups.texi
@@ -807,7 +807,7 @@ If you just want to automatically auto-revert every
 
 @example
 (setq-local buffer-stale-function
-     #'(lambda (&optional noconfirm) 'fast))
+     (lambda (&optional noconfirm) 'fast))
 @end example
 
 @noindent
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 132a3c85354..e01cfedc4b8 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -4358,7 +4358,7 @@ height.
 @end defun
 
 @defun destroy-fringe-bitmap bitmap
-This function destroy the fringe bitmap identified by @var{bitmap}.
+This function destroys the fringe bitmap identified by @var{bitmap}.
 If @var{bitmap} identifies a standard fringe bitmap, it actually
 restores the standard definition of that bitmap, instead of
 eliminating it entirely.
@@ -6926,7 +6926,7 @@ end of the buffer continues from the other end.  If
 is displayed.  Any button with a non-@code{nil} @code{skip} property
 is skipped over.  Returns the button found, and signals an error if no
 buttons can be found.  If @var{no-error} in non-@code{nil}, return nil
-instead of signalling the error.
+instead of signaling the error.
 @end deffn
 
 @deffn Command backward-button n &optional wrap display-message
@@ -6938,7 +6938,7 @@ end of the buffer continues from the other end.  If
 is displayed.  Any button with a non-@code{nil} @code{skip} property
 is skipped over.  Returns the button found, and signals an error if no
 buttons can be found.  If @var{no-error} in non-@code{nil}, return nil
-instead of signalling the error.
+instead of signaling the error.
 @end deffn
 
 @defun next-button pos &optional count-current
diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi
index cfef5c12d1e..5970e7cf801 100644
--- a/doc/lispref/edebug.texi
+++ b/doc/lispref/edebug.texi
@@ -858,7 +858,7 @@ to a non-@code{nil} value.
   Here is an example of code that creates a circular structure:
 
 @example
-(setq a '(x y))
+(setq a (list 'x 'y))
 (setcar a a)
 @end example
 
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index cfd96f7aa68..bba1b63115f 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -297,6 +297,7 @@ Lisp Data Types
 * Circular Objects::        Read syntax for circular structure.
 * Type Predicates::         Tests related to types.
 * Equality Predicates::     Tests of equality between any two objects.
+* Constants and Mutability::  Whether an object's value can change.
 
 Programming Types
 
diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi
index f6f36ed3427..021604c5142 100644
--- a/doc/lispref/eval.texi
+++ b/doc/lispref/eval.texi
@@ -158,6 +158,12 @@ contents unchanged.
 @end group
 @end example
 
+  A self-evaluating form yields constant conses, vectors and strings, and you
+should not attempt to modify their contents via @code{setcar}, @code{aset} or
+similar operations.  The Lisp interpreter might unify the constants
+yielded by your program's self-evaluating forms, so that these
+constants might share structure.  @xref{Constants and Mutability}.
+
   It is common to write numbers, characters, strings, and even vectors
 in Lisp code, taking advantage of the fact that they self-evaluate.
 However, it is quite unusual to do this for types that lack a read
@@ -558,6 +564,8 @@ and vectors.)
 
 @defspec quote object
 This special form returns @var{object}, without evaluating it.
+The returned value is a constant, and should not be modified.
+@xref{Constants and Mutability}.
 @end defspec
 
 @cindex @samp{'} for quoting
@@ -612,10 +620,12 @@ only part of a list, while computing and substituting other parts.
 
   @dfn{Backquote constructs} allow you to quote a list, but
 selectively evaluate elements of that list.  In the simplest case, it
-is identical to the special form @code{quote}
+is identical to the special form
 @iftex
+@code{quote}.
 @end iftex
 @ifnottex
+@code{quote}
 (described in the previous section; @pxref{Quoting}).
 @end ifnottex
 For example, these two forms yield identical results:
@@ -693,6 +703,9 @@ Here are some examples:
 @end group
 @end example
 
+If a subexpression of a backquote construct has no substitutions or
+splices, it acts like @code{quote} in that it yields constant conses,
+vectors and strings that should not be modified.
 
 @node Eval
 @section Eval
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 5cf67ba6473..bc8ec0ef1b0 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -970,7 +970,7 @@ string.
 @end group
 
 @group
-(mapconcat (function (lambda (x) (format "%c" (1+ x))))
+(mapconcat (lambda (x) (format "%c" (1+ x)))
            "HAL-8000"
            "")
      @result{} "IBM.9111"
@@ -2287,7 +2287,7 @@ function) as a generalized variable.  @var{setter} can be a symbol in which
 case it will be passed to @code{gv-define-simple-setter}, or it can be of the
 form @code{(lambda (@var{arg}) @var{body})} in which case that function will
 additionally have access to the macro (or function)'s arguments and it will
-passed to @code{gv-define-setter}.
+be passed to @code{gv-define-setter}.
 
 @end table
 
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index eea1fd2e8f1..9b3c4fcb23d 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -175,49 +175,47 @@ All symbols that have PATTERN in their name are described
 in the *Help* buffer."
   (interactive "sDescribe symbols matching: ")
   (let ((describe-func
-         (function
-          (lambda (s)
+         (lambda (s)
 @end group
 @group
-            ;; @r{Print description of symbol.}
-            (if (fboundp s)             ; @r{It is a function.}
-                (princ
-                 (format "%s\t%s\n%s\n\n" s
-                   (if (commandp s)
-                       (let ((keys (where-is-internal s)))
-                         (if keys
-                             (concat
-                              "Keys: "
-                              (mapconcat 'key-description
-                                         keys " "))
-                           "Keys: none"))
-                     "Function")
+           ;; @r{Print description of symbol.}
+           (if (fboundp s)             ; @r{It is a function.}
+               (princ
+                (format "%s\t%s\n%s\n\n" s
+                  (if (commandp s)
+                      (let ((keys (where-is-internal s)))
+                        (if keys
+                            (concat
+                             "Keys: "
+                             (mapconcat 'key-description
+                                        keys " "))
+                          "Keys: none"))
+                    "Function")
 @end group
 @group
-                   (or (documentation s)
-                       "not documented"))))
+                  (or (documentation s)
+                      "not documented"))))
 
-            (if (boundp s)              ; @r{It is a variable.}
+           (if (boundp s)              ; @r{It is a variable.}
 @end group
 @group
-                (princ
-                 (format "%s\t%s\n%s\n\n" s
-                   (if (custom-variable-p s)
-                       "Option " "Variable")
+               (princ
+                (format "%s\t%s\n%s\n\n" s
+                  (if (custom-variable-p s)
+                      "Option " "Variable")
 @end group
 @group
-                   (or (documentation-property
-                         s 'variable-documentation)
-                       "not documented")))))))
+                  (or (documentation-property
+                        s 'variable-documentation)
+                      "not documented"))))))
         sym-list)
 @end group
 
 @group
     ;; @r{Build a list of symbols that match pattern.}
-    (mapatoms (function
-               (lambda (sym)
-                 (if (string-match pattern (symbol-name sym))
-                     (setq sym-list (cons sym sym-list))))))
+    (mapatoms (lambda (sym)
+                (if (string-match pattern (symbol-name sym))
+                    (setq sym-list (cons sym sym-list)))))
 @end group
 
 @group
diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index 2c90d208c02..130ff0d8671 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -1441,10 +1441,10 @@ Here is an example showing a keymap before and after substitution:
 
 @smallexample
 @group
-(setq map '(keymap
-            (?1 . olddef-1)
-            (?2 . olddef-2)
-            (?3 . olddef-1)))
+(setq map (list 'keymap
+                (cons ?1 olddef-1)
+                (cons ?2 olddef-2)
+                (cons ?3 olddef-1)))
 @result{} (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1))
 @end group
 
@@ -2226,14 +2226,11 @@ right value for selecting that button.  Clicking on the button should
 set the variable so that the button you clicked on becomes selected.
 
 @item :key-sequence @var{key-sequence}
-This property specifies which key sequence is likely to be bound to the
-same command invoked by this menu item.  If you specify a correct key
-sequence, that sequence will be preferred over others.
-
-If you specify an incorrect key sequence, it has no effect; before Emacs
-displays @var{key-sequence} in the menu, it verifies that
-@var{key-sequence} is really equivalent to this menu item.  Specifying
-@code{nil} for @var{key-sequence} is equivalent to the
+This property specifies which key sequence to display as keyboard equivalent.
+Before Emacs displays @var{key-sequence} in the menu, it verifies that
+@var{key-sequence} is really equivalent to this menu item, so it only
+has an effect if you specify a correct key sequence.
+Specifying @code{nil} for @var{key-sequence} is equivalent to the
 @code{:key-sequence} attribute being absent.
 
 @item :keys @var{string}
@@ -2916,17 +2913,17 @@ the following:
 
 @table @code
 @item :keys @var{keys}
-@var{keys} is a keyboard equivalent to the menu item (a string).  This
-is normally not needed, as keyboard equivalents are computed
+@var{keys} is a string to display as keyboard equivalent to the menu item.
+This is normally not needed, as keyboard equivalents are computed
 automatically.  @var{keys} is expanded with
 @code{substitute-command-keys} before it is displayed (@pxref{Keys in
 Documentation}).
 
 @item :key-sequence @var{keys}
-@var{keys} is a hint for speeding up Emacs's first display of the
-menu.  It should be @code{nil} if you know that the menu item has no keyboard
-equivalent; otherwise it should be a string or vector specifying a
-keyboard equivalent for the menu item.
+@var{keys} is a hint indicating which key sequence to display as
+keyboard equivalent, in case the command is bound to several key sequences.
+It has no effect if @var{keys} is not bound to same command as this
+menu item.
 
 @item :active @var{enable}
 @var{enable} is an expression; if it evaluates to @code{nil}, the item
diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index 27fa5385e35..1125af7bec3 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -866,10 +866,15 @@ foo                       ;; @r{@code{foo} was changed.}
 @node Modifying Lists
 @section Modifying Existing List Structure
 @cindex destructive list operations
+@cindex mutable lists
 
   You can modify the @sc{car} and @sc{cdr} contents of a cons cell with the
 primitives @code{setcar} and @code{setcdr}.  These are destructive
 operations because they change existing list structure.
+Destructive operations should be applied only to mutable lists,
+that is, lists constructed via @code{cons}, @code{list} or similar
+operations.  Lists created by quoting are constants and should not be
+changed by destructive operations.  @xref{Constants and Mutability}.
 
 @cindex CL note---@code{rplaca} vs @code{setcar}
 @quotation
@@ -906,7 +911,7 @@ value @var{object}.  For example:
 
 @example
 @group
-(setq x '(1 2))
+(setq x (list 1 2))  ; @r{Create a mutable list.}
      @result{} (1 2)
 @end group
 @group
@@ -926,8 +931,8 @@ these lists.  Here is an example:
 
 @example
 @group
-;; @r{Create two lists that are partly shared.}
-(setq x1 '(a b c))
+;; @r{Create two mutable lists that are partly shared.}
+(setq x1 (list 'a 'b 'c))
      @result{} (a b c)
 (setq x2 (cons 'z (cdr x1)))
      @result{} (z b c)
@@ -1017,11 +1022,11 @@ reached via the @sc{cdr}.
 
 @example
 @group
-(setq x '(1 2 3))
+(setq x (list 1 2 3))  ; @r{Create a mutable list.}
      @result{} (1 2 3)
 @end group
 @group
-(setcdr x '(4))
+(setcdr x '(4))  ; @r{Modify the list's tail to be a constant list.}
      @result{} (4)
 @end group
 @group
@@ -1037,7 +1042,7 @@ the @sc{cdr} of the first cons cell:
 
 @example
 @group
-(setq x1 '(a b c))
+(setq x1 (list 'a 'b 'c))
      @result{} (a b c)
 (setcdr x1 (cdr (cdr x1)))
      @result{} (c)
@@ -1069,7 +1074,7 @@ of this list.
 
 @example
 @group
-(setq x1 '(a b c))
+(setq x1 (list 'a 'b 'c))
      @result{} (a b c)
 (setcdr x1 (cons 'd (cdr x1)))
      @result{} (d b c)
@@ -1130,11 +1135,11 @@ Unlike @code{append} (@pxref{Building Lists}), the @var{lists} are
 
 @example
 @group
-(setq x '(1 2 3))
+(setq x (list 1 2 3))  ; @r{Create a mutable list.}
      @result{} (1 2 3)
 @end group
 @group
-(nconc x '(4 5))
+(nconc x '(4 5))  ; @r{Modify the list's tail to be a constant list.}
      @result{} (1 2 3 4 5)
 @end group
 @group
@@ -1150,7 +1155,7 @@ list:
 
 @example
 @group
-(setq x '(1 2 3))
+(setq x (list 1 2 3))
      @result{} (1 2 3)
 @end group
 @group
@@ -1163,11 +1168,13 @@ x
 @end group
 @end example
 
-However, the other arguments (all but the last) must be lists.
+However, the other arguments (all but the last) should be mutable lists.
 
-A common pitfall is to use a quoted constant list as a non-last
-argument to @code{nconc}.  If you do this, your program will change
-each time you run it!  Here is what happens:
+A common pitfall is to use a constant list as a non-last
+argument to @code{nconc}.  If you do this, the resulting behavior
+is undefined.  It is possible that your program will change
+each time you run it!  Here is what might happen (though this
+is not guaranteed to happen):
 
 @smallexample
 @group
@@ -1270,7 +1277,7 @@ removing it involves changing the @sc{cdr}s (@pxref{Setcdr}).
 
 @example
 @group
-(setq sample-list '(a b c (4)))
+(setq sample-list (list 'a 'b 'c '(4)))
      @result{} (a b c (4))
 @end group
 @group
@@ -1303,12 +1310,12 @@ into the variable that held the original list:
 (setq flowers (delq 'rose flowers))
 @end example
 
-In the following example, the @code{(4)} that @code{delq} attempts to match
-and the @code{(4)} in the @code{sample-list} are not @code{eq}:
+In the following example, the @code{(list 4)} that @code{delq} attempts to match
+and the @code{(4)} in the @code{sample-list} are @code{equal} but not @code{eq}:
 
 @example
 @group
-(delq '(4) sample-list)
+(delq (list 4) sample-list)
      @result{} (a c (4))
 @end group
 @end example
@@ -1324,7 +1331,7 @@ of @code{list}.
 
 @example
 @group
-(setq sample-list '(a b c a b c))
+(setq sample-list (list 'a 'b 'c 'a 'b 'c))
      @result{} (a b c a b c)
 @end group
 @group
@@ -1349,12 +1356,12 @@ Compare this with @code{memq}:
 
 @example
 @group
-(memql 1.2 '(1.1 1.2 1.3))  ; @r{@code{1.2} and @code{1.2} are @code{eql}.}
+(memql 1.2 '(1.1 1.2 1.3))  ; @r{@code{1.2} and @code{1.2} must be @code{eql}.}
      @result{} (1.2 1.3)
 @end group
 @group
-(memq 1.2 '(1.1 1.2 1.3))  ; @r{@code{1.2} and @code{1.2} are not @code{eq}.}
-     @result{} nil
+(memq 1.2 '(1.1 1.2 1.3))  ; @r{@code{1.2} and @code{1.2} need not be @code{eq}.}
+     @result{} nil         ; @r{... or it might be @code{(1.2 1.3)}.}
 @end group
 @end example
 @end defun
@@ -1373,11 +1380,11 @@ Compare this with @code{memq}:
 
 @example
 @group
-(member '(2) '((1) (2)))  ; @r{@code{(2)} and @code{(2)} are @code{equal}.}
+(member (list 2) '((1) (2)))  ; @r{@code{(list 2)} and @code{(2)} are @code{equal}.}
      @result{} ((2))
 @end group
 @group
-(memq '(2) '((1) (2)))    ; @r{@code{(2)} and @code{(2)} are not @code{eq}.}
+(memq (list 2) '((1) (2)))    ; @r{@code{(list 2)} and @code{(2)} are not @code{eq}.}
      @result{} nil
 @end group
 @group
@@ -1407,7 +1414,7 @@ For example:
 
 @example
 @group
-(setq l '((2) (1) (2)))
+(setq l (list '(2) '(1) '(2)))
 (delete '(2) l)
      @result{} ((1))
 l
@@ -1416,7 +1423,7 @@ l
 ;; @r{write @code{(setq l (delete '(2) l))}.}
 @end group
 @group
-(setq l '((2) (1) (2)))
+(setq l (list '(2) '(1) '(2)))
 (delete '(1) l)
      @result{} ((2) (2))
 l
@@ -1618,9 +1625,10 @@ keys may not be symbols:
       '(("simple leaves" . oak)
         ("compound leaves" . horsechestnut)))
 
-(assq "simple leaves" leaves)
+;; @r{The @code{copy-sequence} means the keys are not @code{eq}.}
+(assq (copy-sequence "simple leaves") leaves)
      @result{} nil
-(assoc "simple leaves" leaves)
+(assoc (copy-sequence "simple leaves") leaves)
      @result{} ("simple leaves" . oak)
 @end smallexample
 @end defun
@@ -1759,7 +1767,7 @@ correct results, use the return value of @code{assq-delete-all} rather
 than looking at the saved value of @var{alist}.
 
 @example
-(setq alist '((foo 1) (bar 2) (foo 3) (lose 4)))
+(setq alist (list '(foo 1) '(bar 2) '(foo 3) '(lose 4)))
      @result{} ((foo 1) (bar 2) (foo 3) (lose 4))
 (assq-delete-all 'foo alist)
      @result{} ((bar 2) (lose 4))
@@ -1926,7 +1934,7 @@ function returns the modified property list, so you can store that back
 in the place where you got @var{plist}.  For example,
 
 @example
-(setq my-plist '(bar t foo 4))
+(setq my-plist (list 'bar t 'foo 4))
      @result{} (bar t foo 4)
 (setq my-plist (plist-put my-plist 'foo 69))
      @result{} (bar t foo 69)
diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi
index 855dff2130a..3e9f2221020 100644
--- a/doc/lispref/objects.texi
+++ b/doc/lispref/objects.texi
@@ -46,6 +46,10 @@ you store in it, type and all.  (Actually, a small number of Emacs
 Lisp variables can only take on values of a certain type.
 @xref{Variables with Restricted Values}.)
 
+  Some Lisp objects are @dfn{constant}: their values never change.
+Others are @dfn{mutable}: their values can be changed via destructive
+operations that involve side effects.
+
   This chapter describes the purpose, printed representation, and read
 syntax of each of the standard types in GNU Emacs Lisp.  Details on how
 to use these types can be found in later chapters.
@@ -59,6 +63,7 @@ to use these types can be found in later chapters.
 * Circular Objects::            Read syntax for circular structure.
 * Type Predicates::             Tests related to types.
 * Equality Predicates::         Tests of equality between any two objects.
+* Constants and Mutability::    Whether an object's value can change.
 @end menu
 
 @node Printed Representation
@@ -2377,3 +2382,46 @@ that for two strings to be equal, they have the same text properties.
 @end group
 @end example
 @end defun
+
+@node Constants and Mutability
+@section Constants and Mutability
+@cindex constants
+@cindex mutable objects
+
+  Some Lisp objects are constant: their values never change.
+For example, you can create a new integer by calculating one, but you
+cannot modify the value of an existing integer.
+
+  Other Lisp objects are mutable: their values can be changed
+via destructive operations involving side effects.  For example, an
+existing marker can be changed by moving the marker to point to
+somewhere else.
+
+  Although numbers are always constants and markers are always
+mutable, some types contain both constant and mutable members.  These
+types include conses, vectors, strings, and symbols.  For example, the string
+literal @code{"aaa"} yields a constant string, whereas the function
+call @code{(make-string 3 ?a)} yields a mutable string that can be
+changed via later calls to @code{aset}.
+
+  Trying to modify a constant variable signals an error
+(@pxref{Constant Variables}).
+A program should not attempt to modify other types of constants because the
+resulting behavior is undefined: the Lisp interpreter might or might
+not detect the error, and if it does not detect the error the
+interpreter can behave unpredictably thereafter.  Another way to put
+this is that although mutable objects are safe to change and constant
+symbols reliably reject attempts to change them, other constants are
+not safely mutable: if you try to change one your program might
+behave as you expect but it might crash or worse.  This problem occurs
+with types that have both constant and mutable members, and that have
+mutators like @code{setcar} and @code{aset} that are valid on mutable
+objects but hazardous on constants.
+
+  When the same constant occurs multiple times in a program, the Lisp
+interpreter might save time or space by reusing existing constants or
+constant components.  For example, @code{(eq "abc" "abc")} returns
+@code{t} if the interpreter creates only one instance of the string
+constant @code{"abc"}, and returns @code{nil} if it creates two
+instances.  Lisp programs should be written so that they work
+regardless of whether this optimization is in use.
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index e72858bbf1a..5c0b1e2edf0 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -2617,7 +2617,7 @@ if it is non-@code{nil}; this can be overridden by binding
 This variable is non-@code{nil} when Emacs is running in batch mode.
 @end defvar
 
-If Emacs exits due to signalling an error in batch mode, the exit
+If Emacs exits due to signaling an error in batch mode, the exit
 status of the Emacs command is non-zero:
 
 @example
diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi
index 1a3a04f680b..1cb0d05cc7b 100644
--- a/doc/lispref/sequences.texi
+++ b/doc/lispref/sequences.texi
@@ -183,11 +183,11 @@ for other ways to copy sequences.
 
 @example
 @group
-(setq bar '(1 2))
+(setq bar (list 1 2))  ; @r{Create a mutable list.}
      @result{} (1 2)
 @end group
 @group
-(setq x (vector 'foo bar))
+(setq x (vector 'foo bar))  ; @r{Create a mutable vector.}
      @result{} [foo (1 2)]
 @end group
 @group
@@ -278,7 +278,7 @@ Unlike @code{reverse} the original @var{sequence} may be modified.
 
 @example
 @group
-(setq x '(a b c))
+(setq x (list 'a 'b 'c))  ; @r{Create a mutable list.}
      @result{} (a b c)
 @end group
 @group
@@ -320,7 +320,7 @@ presented graphically:
   For the vector, it is even simpler because you don't need setq:
 
 @example
-(setq x [1 2 3 4])
+(setq x (copy-sequence [1 2 3 4]))  ; @r{Create a mutable vector.}
      @result{} [1 2 3 4]
 (nreverse x)
      @result{} [4 3 2 1]
@@ -330,7 +330,7 @@ x
 
 Note that unlike @code{reverse}, this function doesn't work with strings.
 Although you can alter string data by using @code{aset}, it is strongly
-encouraged to treat strings as immutable.
+encouraged to treat strings as immutable even when they are mutable.
 
 @end defun
 
@@ -374,11 +374,11 @@ appears in a different position in the list due to the change of
 
 @example
 @group
-(setq nums '(1 3 2 6 5 4 0))
+(setq nums (list 1 3 2 6 5 4 0))  ; @r{Create a mutable list.}
      @result{} (1 3 2 6 5 4 0)
 @end group
 @group
-(sort nums '<)
+(sort nums #'<)
      @result{} (0 1 2 3 4 5 6)
 @end group
 @group
@@ -396,7 +396,7 @@ of @code{sort} and use that.  Most often we store the result back into
 the variable that held the original list:
 
 @example
-(setq nums (sort nums '<))
+(setq nums (sort nums #'<))
 @end example
 
 For the better understanding of what stable sort is, consider the following
@@ -1228,7 +1228,7 @@ This function sets the @var{index}th element of @var{array} to be
 
 @example
 @group
-(setq w [foo bar baz])
+(setq w (vector 'foo 'bar 'baz))  ; @r{Create a mutable vector.}
      @result{} [foo bar baz]
 (aset w 0 'fu)
      @result{} fu
@@ -1237,7 +1237,8 @@ w
 @end group
 
 @group
-(setq x "asdfasfd")
+;; @r{@code{copy-sequence} creates a mutable string.}
+(setq x (copy-sequence "asdfasfd"))
      @result{} "asdfasfd"
 (aset x 3 ?Z)
      @result{} 90
@@ -1246,6 +1247,10 @@ x
 @end group
 @end example
 
+The @var{array} should be mutable; that is, it should not be a constant,
+such as the constants created via quoting or via self-evaluating forms.
+@xref{Constants and Mutability}.
+
 If @var{array} is a string and @var{object} is not a character, a
 @code{wrong-type-argument} error results.  The function converts a
 unibyte string to multibyte if necessary to insert a character.
@@ -1257,7 +1262,8 @@ each element of @var{array} is @var{object}.  It returns @var{array}.
 
 @example
 @group
-(setq a [a b c d e f g])
+;; @r{Create a mutable vector and then fill it with zeros.}
+(setq a (copy-sequence [a b c d e f g]))
      @result{} [a b c d e f g]
 (fillarray a 0)
      @result{} [0 0 0 0 0 0 0]
@@ -1265,7 +1271,8 @@ a
      @result{} [0 0 0 0 0 0 0]
 @end group
 @group
-(setq s "When in the course")
+;; @r{Create a mutable string and then fill it with "-".}
+(setq s (copy-sequence "When in the course"))
      @result{} "When in the course"
 (fillarray s ?-)
      @result{} "------------------"
@@ -1302,7 +1309,9 @@ same way in Lisp input.
   A vector, like a string or a number, is considered a constant for
 evaluation: the result of evaluating it is the same vector.  This does
 not evaluate or even examine the elements of the vector.
-@xref{Self-Evaluating Forms}.
+@xref{Self-Evaluating Forms}.  Vectors written with square brackets
+are constants and should not be modified via @code{aset} or other
+destructive operations.  @xref{Constants and Mutability}.
 
   Here are examples illustrating these principles:
 
@@ -1565,14 +1574,14 @@ For example, here is how to examine the elements of the syntax table:
 @example
 (let (accumulator)
    (map-char-table
-    #'(lambda (key value)
-        (setq accumulator
-              (cons (list
-                     (if (consp key)
-                         (list (car key) (cdr key))
-                       key)
-                     value)
-                    accumulator)))
+    (lambda (key value)
+      (setq accumulator
+            (cons (list
+                   (if (consp key)
+                       (list (car key) (cdr key))
+                     key)
+                   value)
+                  accumulator)))
     (syntax-table))
    accumulator)
 @result{}
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 14cabc5d79d..a4c9c2549c5 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -51,10 +51,8 @@ by a distinguished character code.
 operate on them with the general array and sequence functions documented
 in @ref{Sequences Arrays Vectors}.  For example, you can access or
 change individual characters in a string using the functions @code{aref}
-and @code{aset} (@pxref{Array Functions}).  However, note that
-@code{length} should @emph{not} be used for computing the width of a
-string on display; use @code{string-width} (@pxref{Size of Displayed
-Text}) instead.
+and @code{aset} (@pxref{Array Functions}).  However, you should not
+try to change the contents of constant strings (@pxref{Modifying Strings}).
 
   There are two text representations for non-@acronym{ASCII}
 characters in Emacs strings (and in buffers): unibyte and multibyte.
@@ -89,6 +87,9 @@ copy them into buffers.  @xref{Character Type}, and @ref{String Type},
 for information about the syntax of characters and strings.
 @xref{Non-ASCII Characters}, for functions to convert between text
 representations and to encode and decode character codes.
+Also, note that @code{length} should @emph{not} be used for computing
+the width of a string on display; use @code{string-width} (@pxref{Size
+of Displayed Text}) instead.
 
 @node Predicates for Strings
 @section Predicates for Strings
@@ -380,6 +381,11 @@ usual value is @w{@code{"[ \f\t\n\r\v]+"}}.
 @cindex modifying strings
 @cindex string modification
 
+  You can alter the contents of a mutable string via operations
+described in this section.  However, you should not try to use these
+operations to alter the contents of a constant string.
+@xref{Constants and Mutability}.
+
   The most basic way to alter the contents of an existing string is with
 @code{aset} (@pxref{Array Functions}).  @code{(aset @var{string}
 @var{idx} @var{char})} stores @var{char} into @var{string} at index
@@ -591,7 +597,7 @@ for sorting (@pxref{Sequence Functions}):
 
 @example
 @group
-(sort '("11" "12" "1 1" "1 2" "1.1" "1.2") 'string-collate-lessp)
+(sort (list "11" "12" "1 1" "1 2" "1.1" "1.2") 'string-collate-lessp)
      @result{} ("11" "1 1" "1.1" "12" "1 2" "1.2")
 @end group
 @end example
@@ -608,7 +614,7 @@ systems.  The @var{locale} value of @code{"POSIX"} or @code{"C"} lets
 
 @example
 @group
-(sort '("11" "12" "1 1" "1 2" "1.1" "1.2")
+(sort (list "11" "12" "1 1" "1 2" "1.1" "1.2")
       (lambda (s1 s2) (string-collate-lessp s1 s2 "POSIX")))
      @result{} ("1 1" "1 2" "1.1" "1.2" "11" "12")
 @end group
diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi
index ad45a8edaff..9eb99a0ac92 100644
--- a/doc/lispref/syntax.texi
+++ b/doc/lispref/syntax.texi
@@ -1118,9 +1118,9 @@ bidi-class}).
     ;; 'bidi-class' Unicode property is R, AL, or RLO --
     ;; these have a right-to-left directionality.
     (map-char-table
-     #'(lambda (key val)
-         (if (memq val '(R AL RLO))
-             (modify-category-entry key ?R category-table)))
+     (lambda (key val)
+       (if (memq val '(R AL RLO))
+           (modify-category-entry key ?R category-table)))
      uniprop-table)
     category-table))
 @end example
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index ffdf952b081..58424a4231b 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -2073,11 +2073,10 @@ its @code{sort-subr} call looks like this:
 @example
 @group
 (sort-subr reverse
-           (function
-            (lambda ()
-              (while (and (not (eobp))
-                          (looking-at paragraph-separate))
-                (forward-line 1))))
+           (lambda ()
+             (while (and (not (eobp))
+                         (looking-at paragraph-separate))
+               (forward-line 1)))
            'forward-paragraph)
 @end group
 @end example
@@ -4679,7 +4678,7 @@ expanded when the header line is computed.  To do this, the
 above.  @var{specification} is an alist that has elements where the
 @code{car} is a character and the @code{cdr} is the substitution.
 
-If @code{ONLY-PRESENT} is @code{nil}, errors will be signalled if a
+If @code{ONLY-PRESENT} is @code{nil}, errors will be signaled if a
 format character has been used that's not present in
 @var{specification}.  If it's non-@code{nil}, that format
 specification is left verbatim in the result.
@@ -5725,7 +5724,7 @@ made within the @code{combine-after-change-calls} body.
 @code{after-change-functions} within
 the body of a @code{combine-after-change-calls} form.
 
-@strong{Warning:} if the changes you combine occur in widely scattered
+@strong{Warning:} If the changes you combine occur in widely scattered
 parts of the buffer, this will still work, but it is not advisable,
 because it may lead to inefficient behavior for some change hook
 functions.