Improve wording about constants

Thanks to Štěpán Němec and Drew Adams for reviews of recent changes.
* doc/lispref/eval.texi (Quoting): Give an example.
* doc/lispref/lists.texi (Association Lists): Simplify example code.
* doc/lispref/objects.texi (Lisp Data Types)
(Constants and Mutability): Clarify wording.

3 files changed, 23 insertions, 11 deletions

diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi
index 021604c5142..baddce4d9c9 100644
--- a/doc/lispref/eval.texi
+++ b/doc/lispref/eval.texi
@@ -606,6 +606,12 @@ Here are some examples of expressions that use @code{quote}:
 @end group
 @end example
 
+  Although the expressions @code{(list '+ 1 2)} and @code{'(+ 1 2)}
+both yield lists equal to @code{(+ 1 2)}, the former yields a
+freshly-minted mutable list whereas the latter yields a constant list
+built from conses that may be shared with other constants.
+@xref{Constants and Mutability}.
+
   Other quoting constructs include @code{function} (@pxref{Anonymous
 Functions}), which causes an anonymous lambda expression written in Lisp
 to be compiled, and @samp{`} (@pxref{Backquote}), which is used to quote
diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index 1125af7bec3..ea44e01f48a 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -1625,10 +1625,9 @@ 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)
+(assq "simple leaves" leaves)
+     @result{} @r{Unspecified; might be @code{nil} or non-@code{nil}.}
+(assoc "simple leaves" leaves)
      @result{} ("simple leaves" . oak)
 @end smallexample
 @end defun
diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi
index abd258eb537..1eda94ab63e 100644
--- a/doc/lispref/objects.texi
+++ b/doc/lispref/objects.texi
@@ -46,7 +46,7 @@ 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.
+  Some Lisp objects are @dfn{constant}: their values should never change.
 Others are @dfn{mutable}: their values can be changed via destructive
 operations that involve side effects.
 
@@ -2384,22 +2384,28 @@ that for two strings to be equal, they have the same text properties.
 @cindex constants
 @cindex mutable objects
 
-  Some Lisp objects are constant: their values never change.
+  Some Lisp objects are constant: their values should never change
+during a single execution of Emacs running well-behaved Lisp code.
 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
+  Other Lisp objects are mutable: it is safe to change their values
 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
+  Although all numbers are constants and all markers are
 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}.
 
+  A mutable object can become constant if it is passed to the
+@code{eval} function, because a program should not modify an object
+that is being evaluated.  The reverse does not occur: constant objects
+should stay constant.
+
   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
@@ -2407,9 +2413,10 @@ 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
+variables reliably prevent attempts to change them, other constants
+are not safely mutable: if a misbehaving program tries to change such a
+constant then the constant's value might actually change, or the
+program 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.