* doc/dict.n (dict with): [Bug 3474512]: Explain better what is going on when a dictionary key and the dictionary variable collide.

1 files changed, 19 insertions, 0 deletions

diff --git a/doc/dict.n b/doc/dict.n
index b8386f2..361a112 100644
--- a/doc/dict.n
+++ b/doc/dict.n
@@ -251,6 +251,15 @@ exist after the command finishes (unless explicitly \fBunset\fR).
 Note that the mapping of values to variables does not use
 traces; changes to the \fIdictionaryVariable\fR's contents only happen
 when \fIbody\fR terminates.
+.PP
+If the \fIdictionaryVariable\fR contains a value that is not a dictionary at
+the point when the \fIbody\fR terminates (which can easily happen if the name
+is the same as any of the keys in dictionary) then an error occurs at that
+point. This command is thus not recommended for use when the keys in the
+dictionary are expected to clash with the \fIdictionaryVariable\fR name
+itself. Where the contained key does map to a dictionary, the net effect is to
+combine that inner dictionary into the outer dictionary; see the
+\fBEXAMPLES\fR below for an illustration of this.
 .RE
 .SH "DICTIONARY VALUES"
 .PP
@@ -388,6 +397,16 @@ sumDictionary myDict
 puts "dictionary is now \\"$myDict\\""
 #    prints: \fIdictionary is now "a {total 6} b {total 15}"\fR
 .CE
+.PP
+When \fBdict with\fR is used with a key that clashes with the name of the
+dictionary variable:
+.PP
+.CS
+set foo {foo {a b} bar 2 baz 3}
+\fBdict with\fR foo {}
+puts $foo
+#    prints: \fIa b foo {a b} bar 2 baz 3\fR
+.CE
 .SH "SEE ALSO"
 append(n), array(n), foreach(n), incr(n), list(n), lappend(n), set(n)
 .SH KEYWORDS