[Bug 2929546]: Improve the dict documentation.

2 files changed, 63 insertions, 4 deletions

diff --git a/ChangeLog b/ChangeLog
index ba8850b..b846268 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2010-01-19  Donal K. Fellows  <dkf@users.sf.net>
+
+	* doc/dict.n: [Bug 2929546]: Clarify just what [dict with] and [dict
+	update] are doing with variables.
+
 2010-01-18  Andreas Kupries  <andreask@activestate.com>
 
 	* generic/tclIO.c (CreateScriptRecord): [Bug 2918110]: Initialize
diff --git a/doc/dict.n b/doc/dict.n
index 2dc4db3..ffb1500 100644
--- a/doc/dict.n
+++ b/doc/dict.n
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" RCS: @(#) $Id: dict.n,v 1.21 2009/01/07 13:50:03 dkf Exp $
+'\" RCS: @(#) $Id: dict.n,v 1.22 2010/01/19 09:48:58 dkf Exp $
 '\"
 .so man.macros
 .TH dict n 8.5 Tcl "Tcl Built-In Commands"
@@ -107,7 +107,7 @@ dict get $dict foo bar spong
 dict get [dict get [dict get $dict foo] bar] spong
 .CE
 .PP
-If no keys are provided, dict would return a list containing pairs of
+If no keys are provided, \fBdict get\fR will return a list containing pairs of
 elements in a manner similar to \fBarray get\fR. That is, the first
 element of each pair would be the key and the second element would be
 the value for that key.
@@ -208,9 +208,18 @@ to the dictionary within \fIdictionaryVariable\fR (unless
 are silently discarded), even if the result of \fIbody\fR is an error
 or some other kind of exceptional exit. The result of \fBdict
 update\fR is (unless some kind of error occurs) the result of the
-evaluation of \fIbody\fR. Note that the mapping of values to variables
+evaluation of \fIbody\fR.
+.RS
+.PP
+Each \fIvarName\fR is mapped in the scope enclosing the \fBdict update\fR;
+it is recommended that this command only be used in a local scope
+(\fBproc\fRedure, lambda term for \fBapply\fR, or method). Because of
+this, the variables set by \fBdict update\fR will continue to
+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.
+.RE
 .TP
 \fBdict values \fIdictionaryValue \fR?\fIglobPattern\fR?
 .
@@ -233,10 +242,20 @@ dictionary be discarded, and this also happens if the contents of
 \fIdictionaryVariable\fR are adjusted so that the chain of
 dictionaries no longer exists. The result of \fBdict with\fR is
 (unless some kind of error occurs) the result of the evaluation of
-\fIbody\fR. Note that the mapping of values to variables does not use
+\fIbody\fR.
+.RS
+.PP
+The variables are mapped in the scope enclosing the \fBdict with\fR;
+it is recommended that this command only be used in a local scope
+(\fBproc\fRedure, lambda term for \fBapply\fR, or method). Because of
+this, the variables set by \fBdict with\fR will continue to
+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.
+.RE
 .SH "DICTIONARY VALUES"
+.PP
 Dictionaries are values that contain an efficient, order-preserving
 mapping from arbitrary keys to arbitrary values.
 Each key in the dictionary maps to a single value.
@@ -254,6 +273,12 @@ the others are ignored, meaning that,
 and
 .QW "apple carrot apple banana"
 are equivalent dictionaries (with different string representations).
+.PP
+Operations that derive a new dictionary from an old one (e.g., updates
+like \fBdict set\fR and \fBdict unset\fR) preserve the order of keys
+in the dictionary. The exceptions to this are for any new keys they
+add, which are appended to the sequence, and any keys that are
+removed, which are excised from the order.
 .SH EXAMPLES
 .PP
 Basic dictionary usage:
@@ -336,6 +361,35 @@ foreach c [split {abcdefghijklmnopqrstuvwxyz} ""] {
 set upperCaseMap [\fBdict get\fR $capital $env(LANG)]
 set upperCase [string map $upperCaseMap $string]
 .CE
+.PP
+Showing the detail of \fBdict with\fR:
+.PP
+.CS
+proc sumDictionary {varName} {
+   upvar 1 $varName vbl
+   foreach key [\fBdict keys\fR $vbl] {
+      # Manufacture an entry in the subdictionary
+      \fBdict set\fR vbl $key total 0
+      # Add the values and remove the old
+      \fBdict with\fR vbl $key {
+         set total [expr {$x + $y + $z}]
+         unset x y z
+      }
+   }
+   puts "last total was $total, for key $key"
+}
+
+set myDict {
+   a {x 1 y 2 z 3}
+   b {x 6 y 5 z 4}
+}
+
+sumDictionary myDict
+#    prints: \fIlast total was 15, for key b\fR
+
+puts "dictionary is now \\"$myDict\\""
+#    prints: \fIdictionary is now "a {total 6} b {total 15}"\fR
+.CE
 .SH "SEE ALSO"
 append(n), array(n), foreach(n), incr(n), list(n), lappend(n), set(n)
 .SH KEYWORDS