Merge from origin/emacs-27

4b9fbdb5a7 ; Update TODO item about ligature support
03d44acfdd * doc/lispref/control.texi (Processing of Errors): Improve...
b48ab743a8 Minor fixups for mutability doc
6ac2326e5b Don’t use “constant” for values you shouldn’t change

1 files changed, 48 insertions, 45 deletions

diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi
index cd037d663da..83066744121 100644
--- a/doc/lispref/objects.texi
+++ b/doc/lispref/objects.texi
@@ -46,10 +46,6 @@ 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 should 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.
@@ -63,7 +59,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.
+* Mutability::                  Some objects should not be modified.
 @end menu
 
 @node Printed Representation
@@ -2383,51 +2379,58 @@ that for two strings to be equal, they have the same text properties.
 @end example
 @end defun
 
-@node Constants and Mutability
-@section Constants and Mutability
-@cindex constants
+@node Mutability
+@section Mutability
 @cindex mutable objects
 
-  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: 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 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
+  Some Lisp objects should never change.  For example, the Lisp
+expression @code{"aaa"} yields a string, but you should not change
+its contents.  And some objects cannot be changed; for example,
+although you can create a new number by calculating one, Lisp provides
+no operation to change the value of an existing number.
+
+  Other Lisp objects are @dfn{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 never change and all markers are mutable,
+some types have members some of which are mutable and others not.  These
+types include conses, vectors, and strings.  For example,
+although @code{"cons"} and @code{(symbol-name 'cons)} both yield
+strings that should not be changed, @code{(copy-sequence "cons")} and
+@code{(make-string 3 ?a)} both yield mutable strings that can be
 changed via later calls to @code{aset}.
 
-  A mutable object can become constant if it is part of an expression
-that is 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
-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
-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.
-
-  When the same constant occurs multiple times in a program, the Lisp
+  A mutable object stops being mutable if it is part of an expression
+that is evaluated.  For example:
+
+@example
+(let* ((x (list 0.5))
+       (y (eval (list 'quote x))))
+  (setcar x 1.5) ;; The program should not do this.
+  y)
+@end example
+
+@noindent
+Although the list @code{(0.5)} was mutable when it was created, it should not
+have been changed via @code{setcar} because it given to @code{eval}.  The
+reverse does not occur: an object that should not be changed never
+becomes mutable afterwards.
+
+  If a program attempts to change objects that should not be
+changed, the resulting behavior is undefined: the Lisp interpreter
+might signal an error, or it might crash or behave unpredictably in
+other ways.@footnote{This is the behavior specified for languages like
+Common Lisp and C for constants, and this differs from languages like
+JavaScript and Python where an interpreter is required to signal an
+error if a program attempts to change an immutable object.  Ideally the Emacs
+Lisp interpreter will evolve in latter direction.}
+
+  When similar constants occur as parts of a program, the Lisp
 interpreter might save time or space by reusing existing constants or
-constant components.  For example, @code{(eq "abc" "abc")} returns
+their 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
+literal @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.