Proofreading changes to Testscript manual (for/while loops)

1 files changed, 61 insertions, 75 deletions

diff --git a/doc/testscript.cli b/doc/testscript.cli
index e3a9c43..770bcfc 100644
--- a/doc/testscript.cli
+++ b/doc/testscript.cli
@@ -1612,7 +1612,7 @@ description:
   +(':' <text>)
 \
 
-Note that the only purpose of having a separate (from the command flow control
+Note that the only purpose of having separate (from the command flow control
 constructs) variable-only flow control constructs is to remove the error-prone
 requirement of having to specify \c{+} and \c{-} prefixes in group
 setup/teardown.
@@ -1839,48 +1839,31 @@ variable-flow-body:
   *variable-like
 \
 
-A group of variables can be set in a loop, while iterating over elements of a
-potentially empty list and setting the specified variable (called \i{loop
-variable}) to the corresponding element on each iteration. At the end of the
-iteration the loop variable contains the value of the last element, if any.
-
-In the first form the list results from an expression containing variable
-expansions, function calls, eval contexts, and/or literal values. For example:
+A group of variables can be set in a loop while iterating over elements of a
+list. The iteration semantics is the same as in \c{command-for}. For example:
 
 \
-us =
-ls =
-
-for v: $vs
-  us += $string.ucase($v)
-  ls += $string.lcase($v)
+uvalues =
+for v: $values
+  uvalues += $string.ucase($v)
 end
 \
 
-In the second form the list is read from \c{stdin} input. The input data can
-be split into elements at newlines or whitespaces if \c{-n} or \c{-w} option,
-respectively, is specified. This form supports the same set of options as the
-\l{#builtins-set \c{set}} pseudo-builtin. For example:
+Another example:
 
 \
-us =
-ls =
-
+uvalues =
 cat values.txt | for -n v
-  us += $string.ucase($v)
-  ls += $string.lcase($v)
+  uvalues += $string.ucase($v)
 end
 \
 
-This example can actually be simplified as:
+Or using the \c{stdin} redirect:
 
 \
-us =
-ls =
-
+uvalues =
 for -n v <=values.txt
-  us += $string.ucase($v)
-  ls += $string.lcase($v)
+  uvalues += $string.ucase($v)
 end
 \
 
@@ -1897,16 +1880,16 @@ variable-flow-body:
   *variable-like
 \
 
-A group of variables can be set in a loop, while iterating until the condition
-evaluates to \c{false}. The condition \c{command-line} semantics is the same
-as in \c{scope-if}. For example:
+A group of variables can be set in a loop while the condition evaluates to
+\c{true}. The condition \c{command-line} semantics is the same as in
+\c{scope-if}. For example:
 
 \
-r =
+uvalues =
 i = [uint64] 0
-
-while ($i != 2)
-  r += ($vs[$i])
+n = $size($values)
+while ($i != $n)
+  uvalues += $string.ucase($values[$i])
   i += 1
 end
 \
@@ -2018,50 +2001,48 @@ command-flow-body:
   *(variable-line|command-like)
 \
 
-A group of commands can be executed in a loop, while iterating over elements
-of a potentially empty list and setting the specified variable (called \i{loop
-variable}) to the corresponding element on each iteration. At the end of the
-iteration the loop variable contains the value of the last element, if any.
-Note that in a compound test, commands inside \c{command-for} must not end
-with \c{;}. Rather, \c{;} may follow \c{end}.
+A group of commands can be executed in a loop while iterating over elements of
+a list and setting the specified variable (called \i{loop variable}) to the
+corresponding element on each iteration. At the end of the iteration the loop
+variable contains the value of the last element, if any.  Note that in a
+compound test, commands inside \c{command-for} must not end with
+\c{;}. Rather, \c{;} may follow \c{end}.
 
-In the first form the list results from an expression containing variable
-expansions, function calls, eval contexts, and/or literal values. For example:
+The \c{for} loop has two forms: In the first form the list is specified as
+arguments. Similar to the \c{for} loop in the Buildfile language, it can
+contain variable expansions, function calls, evaluation contexts, and/or
+literal values. For example:
 
 \
-ls = ;
-for v: $vs
-  test1 $string.ucase($v)
-  ls += $string.lcase($v)
+for v: $values
+  test1 $v
 end;
-test2 $ls
+test2
 \
 
-In the second form the list is read from \c{stdin} input. The input data can
-be split into elements at newlines or whitespaces if \c{-n} or \c{-w} option,
-respectively, is specified. This form supports the same set of options as the
-\l{#builtins-set \c{set}} pseudo-builtin. For example:
+In the second form the list is read from the \c{stdin} input. The input data
+is split into elements either at whitespaces (default) or newlines, which can
+be controlled with the \c{-n|--newline} and \c{-w|--whitespace} options.
+Overall, this form supports the same set of options as the \l{#builtins-set
+\c{set}} pseudo-builtin. For example:
 
 \
-ls = ;
 cat values.txt | for -n v
-  test1 $string.ucase($v)
-  ls += $string.lcase($v)
-end;
-test2 $ls
+  test1 $v
+end
 \
 
-This example can actually be simplified:
+Or using the \c{stdin} redirect:
 
 \
-ls = ;
 for -n v <=values.txt
-  test1 $string.ucase($v)
-  ls += $string.lcase($v)
-end;
-test2 $ls
+  test1 $v
+end
 \
 
+Both forms can include value attributes enclosed in \c{[]} to be applied to
+each element, again similar to the \l{#builtins-set \c{set}} pseudo-builtin.
+
 
 \h#syntax-command-while|Command-While|
 
@@ -2075,22 +2056,27 @@ command-flow-body:
   *(variable-line|command-like)
 \
 
-A group of commands can be executed in a loop, while iterating until the
-condition evaluates to \c{false}. The condition \c{command-line} semantics is
-the same as in \c{scope-if}. Note that in a compound test, commands inside
-\c{command-while} must not end with \c{;}. Rather, \c{;} may follow
-\c{end}. For example:
+A group of commands can be executed in a loop while a condition evaluates to
+\c{true}. The condition \c{command-line} semantics is the same as in
+\c{scope-if}. Note that in a compound test, commands inside \c{command-while}
+must not end with \c{;}. Rather, \c{;} may follow \c{end}. For example:
 
 \
-r = ;
 i = [uint64] 0;
-while ($i != 2)
-  v = ($vs[$i])
-  test1 $v
-  r += $v
+n = $size($values);
+while ($i != $n)
+  test1 ($values[$i])
   i += 1
 end;
-test2 $r
+test2
+\
+
+Another example:
+
+\
+while test -f $file
+  test1 $file
+end
 \