Clarify that #s(hash-table ...) doesn't always create a new hash table

* doc/lispref/hash.texi (Creating Hash): Note that the printed
representation doesn't necessarily create a new table (bug#23417).

* doc/lispref/lists.texi (Rearrangement): Link to Self-Evaluating
Forms to further expand upon immutability.

2 files changed, 15 insertions, 9 deletions

diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi
index 8781fad30cd..12c6a659079 100644
--- a/doc/lispref/hash.texi
+++ b/doc/lispref/hash.texi
@@ -150,11 +150,11 @@ multiplied by an approximation to this value.  The default for
 @end table
 @end defun
 
-You can also create a new hash table using the printed representation
+You can also create a hash table using the printed representation
 for hash tables.  The Lisp reader can read this printed
 representation, provided each element in the specified hash table has
 a valid read syntax (@pxref{Printed Representation}).  For instance,
-the following specifies a new hash table containing the keys
+the following specifies a hash table containing the keys
 @code{key1} and @code{key2} (both symbols) associated with @code{val1}
 (a symbol) and @code{300} (a number) respectively.
 
@@ -162,6 +162,11 @@ the following specifies a new hash table containing the keys
 #s(hash-table size 30 data (key1 val1 key2 300))
 @end example
 
+Note, however, that when using this in Emacs Lisp code, it's
+undefined whether this creates a new hash table or not.  If you want
+to create a new hash table, you should always use
+@code{make-hash-table} (@pxref{Self-Evaluating Forms}).
+
 @noindent
 The printed representation for a hash table consists of @samp{#s}
 followed by a list beginning with @samp{hash-table}.  The rest of the
diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index c54496f6168..2805b1f5fdc 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -1168,13 +1168,14 @@ x
 @end group
 @end example
 
-However, the other arguments (all but the last) should be mutable lists.
-
-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):
+However, the other arguments (all but the last) should be mutable
+lists.
+
+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
+(@pxref{Self-Evaluating Forms}).  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