tuning up the documentation

1 files changed, 23 insertions, 16 deletions

diff --git a/doc/dict.n b/doc/dict.n
index b9b4767..3bd5530 100644
--- a/doc/dict.n
+++ b/doc/dict.n
@@ -147,23 +147,30 @@ keys are treated as if they map to an empty list, and it is legal for
 there to be no items to append to the list. It is an error for the
 value that the key maps to to not be representable as a list.
 .TP
-\fBdict map {\fIkeyVar valueVar\fB} \fIdictionaryValue body\fR
+\fBdict map \fR{\fIkeyVar valueVar\fR} \fIdictionaryValue body\fR
 .
-This command takes three arguments, the first a two-element list of
-variable names (for the key and value respectively of each mapping in
-the dictionary), the second the dictionary value to iterate across,
-and the third a script to be evaluated for each mapping with the key
-and value variables set appropriately (in the manner of \fBmapeach\fR.)
-In an iteration where the evaluated script completes normally 
-(\fBTCL_OK\fR) the script result is appended to an accumulator list.
-The result of the \fBdict map\fB command is the accumulator list.
-If any evaluation of the body generates a \fBTCL_BREAK\fR result, no 
-further pairs from the dictionary will be iterated over and the 
-\fBdict map\fR command will terminate successfully immediately. If any
-evaluation of the body generates a \fBTCL_CONTINUE\fR result, the
-current iteration is aborted and the accumulator list is not modified.
-The order of iteration is the order in which the keys were inserted into
-the dictionary.
+This command applies a transformation to each element of a dictionary,
+returning a new dictionary. It takes three arguments: the first is a
+two-element list of variable names (for the key and value respectively of each
+mapping in the dictionary), the second the dictionary value to iterate across,
+and the third a script to be evaluated for each mapping with the key and value
+variables set appropriately (in the manner of \fBlmap\fR). In an iteration
+where the evaluated script completes normally (\fBTCL_OK\fR, as opposed to an
+\fBerror\fR, etc.) the result of the script is put into an accumulator
+dictionary using the key that is the current contents of the \fIkeyVar\fR
+variable at that point. The result of the \fBdict map\fB command is the
+accumulator dictionary after all keys have been iterated over.
+.RS
+.PP
+If the evaluation of the body for any particular step generates a \fBbreak\fR,
+no further pairs from the dictionary will be iterated over and the \fBdict
+map\fR command will terminate successfully immediately. If the evaluation of
+the body for a particular step generates a \fBcontinue\fR result, the current
+iteration is aborted and the accumulator dictionary is not modified. The order
+of iteration is the natural order of the dictionary (typically the order in
+which the keys were added to the dictionary; the order is the same as that
+used in \fBdict for\fR).
+.RE
 .TP
 \fBdict merge \fR?\fIdictionaryValue ...\fR?
 .