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

2 files changed, 24 insertions, 0 deletions

diff --git a/ChangeLog b/ChangeLog
index a15a7e9..458bb51 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2012-01-17  Donal K. Fellows  <dkf@users.sf.net>
+
+	* doc/dict.n (dict with): [Bug 3474512]: Explain better what is going
+	on when a dictionary key and the dictionary variable collide.
+
 2012-01-13  Donal K. Fellows  <dkf@users.sf.net>
 
 	* library/http/http.tcl (http::Connect): [Bug 3472316]: Ensure that we
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