Improve mutability documentation

This change was inspired by comments from Štěpán Němec in:
https://lists.gnu.org/r/emacs-devel/2020-04/msg01063.html
* doc/lispref/objects.texi (Lisp Data Types): Mention mutability.
(Constants and mutability): New section.
* doc/lispintro/emacs-lisp-intro.texi (Lists diagrammed)
(Indent Tabs Mode): Improve wording.
* doc/lispref/eval.texi (Self-Evaluating Forms):
Say that they return constants.
* doc/lispref/lists.texi (Sets And Lists):
Fix memql mistake/confusion that I recently introduced.

7 files changed, 69 insertions, 15 deletions

diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi
index 630676d9786..ea16d9ef155 100644
--- a/doc/lispintro/emacs-lisp-intro.texi
+++ b/doc/lispintro/emacs-lisp-intro.texi
@@ -9557,7 +9557,7 @@ part of which is the address of the next pair.  The very last box
 points to the symbol @code{nil}, which marks the end of the list.
 
 @need 1200
-When a variable is set to a list via @code{setq},
+When a variable is set to a list with an operation such as @code{setq},
 it stores the address of the first box in the variable.  Thus,
 evaluation of the expression
 
@@ -17140,7 +17140,7 @@ The following turns off Indent Tabs mode:
 @end smallexample
 
 Note that this line uses @code{setq-default} rather than the
-@code{setq} that we have seen before.  The @code{setq-default}
+@code{setq} that we have seen before; @code{setq-default}
 sets values only in buffers that do not have their own local
 values for the variable.
 
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 46cfab164b7..deb288943af 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 a constant, and you should not attempt
+to modify the constant's contents via @code{setcar}, @code{aset} or
+similar primitives.  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
@@ -559,6 +565,7 @@ 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
diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index c2771b01652..f1acc85616f 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -866,16 +866,15 @@ foo                       ;; @r{@code{foo} was changed.}
 @node Modifying Lists
 @section Modifying Existing List Structure
 @cindex destructive list operations
-@cindex constant lists
 @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 @dfn{mutable} lists,
+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.
+changed by destructive operations.  @xref{Constants and Mutability}.
 
 @cindex CL note---@code{rplaca} vs @code{setcar}
 @quotation
@@ -1169,9 +1168,9 @@ x
 @end group
 @end example
 
-However, the other arguments (all but the last) must be mutable 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
+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
@@ -1359,12 +1358,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 (list 2) '((1) (2)))  ; @r{@code{(list 2)} and @code{(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
@@ -1628,6 +1627,7 @@ keys may not be symbols:
       '(("simple leaves" . oak)
         ("compound leaves" . horsechestnut)))
 
+;; @r{The @code{copy-sequence} means the keys are not @code{eq}.}
 (assq (copy-sequence "simple leaves") leaves)
      @result{} nil
 (assoc (copy-sequence "simple leaves") leaves)
diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi
index 1c4e7e4d4e3..98b001afd2d 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
@@ -2373,3 +2378,43 @@ 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, and strings.  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}.
+
+  A program should not attempt to modify a constant 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 mutable objects are safe to change, whereas constants are
+not safely mutable: if you try to change a constant 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/sequences.texi b/doc/lispref/sequences.texi
index 7a3f26e584f..62d60156fbf 100644
--- a/doc/lispref/sequences.texi
+++ b/doc/lispref/sequences.texi
@@ -1249,7 +1249,7 @@ x
 
 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{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
@@ -1306,10 +1306,10 @@ 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.  Vectors
-written with square brackets are constants and should not be modified
-via @code{aset} or other destructive operations.
-@xref{Self-Evaluating Forms}.
+not evaluate or even examine the elements of the vector.
+@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:
 
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 3acbf538dce..a4c9c2549c5 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -384,6 +384,7 @@ usual value is @w{@code{"[ \f\t\n\r\v]+"}}.
   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}