tuning up the documentation

1 files changed, 38 insertions, 44 deletions

diff --git a/doc/lmap.n b/doc/lmap.n
index 7deb7f9..880b05a 100644
--- a/doc/lmap.n
+++ b/doc/lmap.n
@@ -15,77 +15,71 @@ lmap \- Iterate over all elements in one or more lists and collect results
 .br
 \fBlmap \fIvarlist1 list1\fR ?\fIvarlist2 list2 ...\fR? \fIbody\fR
 .BE
-
 .SH DESCRIPTION
 .PP
-The \fBlmap\fR command implements a loop where the loop
-variable(s) take on values from one or more lists, and the loop returns a list
-of results collected from each iteration.
+The \fBlmap\fR command implements a loop where the loop variable(s) take on
+values from one or more lists, and the loop returns a list of results
+collected from each iteration.
 .PP
-In the simplest case there is one loop variable, \fIvarname\fR,
-and one list, \fIlist\fR, that is a list of values to assign to \fIvarname\fR.
-The \fIbody\fR argument is a Tcl script.
-For each element of \fIlist\fR (in order
-from first to last), \fBlmap\fR assigns the contents of the
-element to \fIvarname\fR as if the \fBlindex\fR command had been used
-to extract the element, then calls the Tcl interpreter to execute
-\fIbody\fR.  If execution of the body completes normally then the result of the
-body is appended to an accumulator list. \fBlmap\fR returns the accumulator
-list.
-
+In the simplest case there is one loop variable, \fIvarname\fR, and one list,
+\fIlist\fR, that is a list of values to assign to \fIvarname\fR. The
+\fIbody\fR argument is a Tcl script. For each element of \fIlist\fR (in order
+from first to last), \fBlmap\fR assigns the contents of the element to
+\fIvarname\fR as if the \fBlindex\fR command had been used to extract the
+element, then calls the Tcl interpreter to execute \fIbody\fR. If execution of
+the body completes normally then the result of the body is appended to an
+accumulator list. \fBlmap\fR returns the accumulator list.
 .PP
-In the general case there can be more than one value list
-(e.g., \fIlist1\fR and \fIlist2\fR),
-and each value list can be associated with a list of loop variables
-(e.g., \fIvarlist1\fR and \fIvarlist2\fR).
-During each iteration of the loop
-the variables of each \fIvarlist\fR are assigned
-consecutive values from the corresponding \fIlist\fR.
-Values in each \fIlist\fR are used in order from first to last,
-and each value is used exactly once.
-The total number of loop iterations is large enough to use
-up all the values from all the value lists.
-If a value list does not contain enough
-elements for each of its loop variables in each iteration,
-empty values are used for the missing elements.
+In the general case there can be more than one value list (e.g., \fIlist1\fR
+and \fIlist2\fR), and each value list can be associated with a list of loop
+variables (e.g., \fIvarlist1\fR and \fIvarlist2\fR). During each iteration of
+the loop the variables of each \fIvarlist\fR are assigned consecutive values
+from the corresponding \fIlist\fR. Values in each \fIlist\fR are used in order
+from first to last, and each value is used exactly once. The total number of
+loop iterations is large enough to use up all the values from all the value
+lists. If a value list does not contain enough elements for each of its loop
+variables in each iteration, empty values are used for the missing elements.
 .PP
-The \fBbreak\fR and \fBcontinue\fR statements may be
-invoked inside \fIbody\fR, with the same effect as in the \fBfor\fR
-and \fBforeach\fR commands. In these cases the body does not complete normally
-and the result is not appended to the accumulator list.
+The \fBbreak\fR and \fBcontinue\fR statements may be invoked inside
+\fIbody\fR, with the same effect as in the \fBfor\fR and \fBforeach\fR
+commands. In these cases the body does not complete normally and the result is
+not appended to the accumulator list.
 .SH EXAMPLES
 .PP
 Zip lists together:
 .PP
 .CS
-'\" Maintainers: notice the tab hacking below!
-.ta 3i
 set list1 {a b c d}
 set list2 {1 2 3 4}
 set zipped [\fBlmap\fR a $list1 b $list2 {list $a $b}] 
 # The value of zipped is "{a 1} {b 2} {c 3} {d 4}"
 .CE
 .PP
-Filter a list:
+Filter a list to remove odd values:
 .PP
 .CS
 set values {1 2 3 4 5 6 7 8}
-proc isGood {n} { expr { ($n % 2) == 0 } }
-set goodOnes [\fBlmap\fR x $values {expr {[isGood $x] ? $x : [continue]}}]
+proc isEven {n} {expr {($n % 2) == 0}}
+set goodOnes [\fBlmap\fR x $values {expr {
+    [isEven $x] ? $x : [continue]
+}}]
 # The value of goodOnes is "2 4 6 8"
 .CE
 .PP
-Take a prefix from a list:
+Take a prefix from a list based on the contents of the list:
 .PP
 .CS
 set values {8 7 6 5 4 3 2 1}
-proc isGood {n} { expr { $n > 3 } }
-set prefix [\fBlmap\fR x $values {expr {[isGood $x] ? $x : [break]}}] 
+proc isGood {counter} {expr {$n > 3}}
+set prefix [\fBlmap\fR x $values {expr {
+    [isGood $x] ? $x : [break]
+}}]
 # The value of prefix is "8 7 6 5 4"
 .CE
-
 .SH "SEE ALSO"
-for(n), while(n), break(n), continue(n), foreach(n)
-
+break(n), continue(n), for(n), foreach(n), while(n)
 .SH KEYWORDS
 foreach, iteration, list, loop, map
+'\" Local Variables:
+'\" mode: nroff
+'\" End: