bug#59595: [PATCH 1/3] Add examples and incomplete wordings.

[Yuval Langer <yuvallangerontheroad@gmail.com>]

---
 doc/ref/api-data.texi | 33 ++++++++++++++++++++++++++++++++-
 1 file changed, 32 insertions(+), 1 deletion(-)

diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi
index 8658b9785..8c18b4d40 100644
--- a/doc/ref/api-data.texi
+++ b/doc/ref/api-data.texi
@@ -4767,7 +4767,7 @@ It also allows further properties to use the same symbols among their
 possible values without becoming ambiguous:
 
 @lisp
-(define car1-properties '((colour . red)
+(define car2-properties '((colour . red)
                           (transmission . manual)
                           (fuel . unleaded)
                           (steering . power-assisted)
@@ -4793,6 +4793,37 @@ extract or change individual pieces of information:
  (locking . manual)))
 @end lisp
 
+Notice that if we try the same @code{assq-set!} call with
+@code{car2-properties}, we get an exception:
+
+@lisp
+(assq-set! car2-properties 'seat-colour 'black)
+@end lisp
+
+This is due to the fact that literal alists are immutable. If you want
+to mutate an alist, you must define it using the @code{acons}
+constructor:
+
+@lisp
+(define car3-properties (acons 'colour 'red
+                        (acons 'transmission 'manual
+                        (acons 'fuel 'unleaded
+                        (acons 'steering 'power-assisted
+                        (acons 'seat-colour 'red
+                        (acons 'locking 'manual '())))))))
+
+(assq-ref car3-properties 'seat-colour) @result{} red
+(assq-set! car3-properties 'seat-colour 'black)
+@result{}
+((colour . red)
+ (transmission . manual)
+ (fuel . unleaded)
+ (steering . power-assisted)
+ (seat-colour . black)
+ (locking . manual)))
+(assq-ref car3-properties 'seat-colour) @result{} black
+@end lisp
+
 Hash tables also have keys, and exactly the same arguments apply to the
 use of symbols in hash tables as in association lists.  The hash value
 that Guile uses to decide where to add a symbol-keyed entry to a hash
-- 
2.30.2