From 2f2dbb199f2bfb89faf306aada4aeaade0a10e61 Mon Sep 17 00:00:00 2001
From: John Kerl <kerl.john.r@gmail.com>
Date: Tue, 7 Jun 2016 23:37:15 -0700
Subject: [PATCH] doc neaten

---
 doc/content-for-reference.html |  6 ++++++
 doc/data/for-srec-example-3.sh |  9 +++++++++
 doc/reference.html             | 26 ++++++++++++++++++++++++++
 3 files changed, 41 insertions(+)
 create mode 100644 doc/data/for-srec-example-3.sh

diff --git a/doc/content-for-reference.html b/doc/content-for-reference.html
index 713702499..f04e01039 100644
--- a/doc/content-for-reference.html
+++ b/doc/content-for-reference.html
@@ -1013,6 +1013,12 @@ itself</b>:
 
 POKI_INCLUDE_AND_RUN_ESCAPED(data/for-srec-example-2.sh)HERE
 
+It can be confusing to modify the stream record while iterating over a copy of it, so
+instead you might find it simpler to use an out-of-stream variable in the loop and only update
+the stream record after the loop:
+
+POKI_INCLUDE_AND_RUN_ESCAPED(data/for-srec-example-3.sh)HERE
+
 <p/><b>No triple-for:</b> As of Miller 4.1.0 there is no C-style triple-for of the form
 
 POKI_CARDIFY{{for (i = 1; i <= 10; i++) { ... } # No such}}HERE
diff --git a/doc/data/for-srec-example-3.sh b/doc/data/for-srec-example-3.sh
new file mode 100644
index 000000000..21611858b
--- /dev/null
+++ b/doc/data/for-srec-example-3.sh
@@ -0,0 +1,9 @@
+mlr --from data/small --opprint put '
+  @sum = 0;
+  for (k,v in $*) {
+    if (isnumeric(v)) {
+      @sum += $[k];
+    }
+  }
+  $sum = @sum
+'
diff --git a/doc/reference.html b/doc/reference.html
index b6c2e6dbb..3bf379622 100644
--- a/doc/reference.html
+++ b/doc/reference.html
@@ -3438,6 +3438,32 @@ wye pan 5 0.5732889198020006  0.8636244699032729  6.436913 25.747654
 </div>
 <p/>
 
+It can be confusing to modify the stream record while iterating over a copy of it, so
+instead you might find it simpler to use an out-of-stream variable in the loop and only update
+the stream record after the loop:
+
+<p/>
+<div class="pokipanel">
+<pre>
+$ mlr --from data/small --opprint put '
+  @sum = 0;
+  for (k,v in $*) {
+    if (isnumeric(v)) {
+      @sum += $[k];
+    }
+  }
+  $sum = @sum
+'
+a   b   i x                   y                   sum
+pan pan 1 0.3467901443380824  0.7268028627434533  2.073593
+eks pan 2 0.7586799647899636  0.5221511083334797  3.280831
+wye wye 3 0.20460330576630303 0.33831852551664776 3.542922
+eks wye 4 0.38139939387114097 0.13418874328430463 4.515588
+wye pan 5 0.5732889198020006  0.8636244699032729  6.436913
+</pre>
+</div>
+<p/>
+
 <p/><b>No triple-for:</b> As of Miller 4.1.0 there is no C-style triple-for of the form
 
 <p/>