Merge pull request #3429 from uzluisf/master

Minor rewording with few examples
Thanks a lot!

Author: JJ

doc/Language/control.pod6

@@ -24,7 +24,7 @@ also be written as:
 =head1 X<Blocks|control flow, blocks>
 
 Like many other languages, Raku uses C<blocks> enclosed by C<{> and C<}> to
-turn a sequence of statements into a single one. It is OK to skip the semicolon
+turn a sequence of statements into a single one. It is OK to omit the semicolon
 between the last statement in a block and the closing C<}>.
 
     { say "Hello"; say "World" }
@@ -129,7 +129,8 @@ the expression it is contained in is evaluated:
     # This says "(..1 ..2 ..3)" not "(..1 ...2 ....3)"
     my $f = "."; say do { $f ~= "." } X~ 1, 2, 3;
 
-In other words, it follows the same reification rules as everything else.
+In other words, it follows the same
+L<reification|/language/glossary#index-entry-Reify> rules as everything else.
 
 Technically, C<do> is a loop which runs exactly one iteration.
 
@@ -574,21 +575,36 @@ for $*IN.lines -> $line { .say }
 
 Iteration variables are always lexical, so you don't need to use C<my> to give
 them the appropriate scope. Also, they are read-only aliases. If you need them
-to be writable, use C«<->» instead of C«->». If you want to modify them
-within the block, add C<is copy>, e.g., C<<for @foo -> $f is copy {...>>.
+to be writable, use C«<->» instead of C«->». Alternatively, you can add
+the L«C«is rw»|/type/Signature#index-entry-trait_is_rw» trait; this performs
+a binding operation so assigning to the parameter changes the value of the
+variable at the caller side. If instead you want to modify copies of the
+arguments within the block, add
+L«C«is copy»|/type/Signature#index-entry-trait_is_copy».
 
 =begin code
 my @foo = 1..3;
-my @bar;
-
 for @foo <-> $value {
-    given $value {
-      when $value %% 2 { $value = $value but "Even" }
-      default { $value = $value but "Odd" }
-    }
-    @bar.push: $value;
+    $value = $value %% 2 ?? "Even" !! "Odd"
+}
+
+say @foo; # OUTPUT: «[Odd Even Odd]»
+
+@foo = 1..3;
+for @foo -> $value is rw {
+    $value = $value %% 2 ?? "Even" !! "Odd"
 }
 
+say @foo; # OUTPUT: «[Odd Even Odd]»
+
+@foo = 1..3;
+my @bar;
+for @foo -> $value is copy {
+    $value = $value %% 2 ?? "Even" !! "Odd";
+    @bar.push: $value
+}
+
+say @foo; # OUTPUT: «[1 2 3]»
 say @bar; # OUTPUT: «[Odd Even Odd]»
 =end code
 
@@ -634,7 +650,7 @@ for 1 {
 
 The first loop creates three elements but they are in a sink context, so its
 C<sink> method is called. In the second loop, its last statement will be in a
- sink context, so it will be also sunk (from version 6.d).
+sink context, so it will be also sunk (from version 6.d).
 
 The C<Empty> constant will act as a no-op for a loop:
 
@@ -677,20 +693,30 @@ X<|lazy list,gather>X<|lazy list,take>
 
 C<gather> is a statement or block prefix that returns a L<sequence|/type/Seq>
 of values. The values come from calls to L<take|/type/Mu#routine_take> in the
-dynamic scope of the C<gather> block.
-
-    my @a = gather {
-        take 1;
-        take 5;
-        take 42;
+dynamic scope of the C<gather> block. In the following example, we implement
+a subroutine to compute the factors of an integer with C<gather> (note that the
+factors are not generated in a strictly increasing order):
+
+    sub factors( Int:D \n ) {
+        my $k = 1;
+        gather {
+            while $k**2 < n {
+                if n %% $k {
+                    take $k;
+                    take n div $k;
+                }
+                $k++;
+            }
+            take $k if $k**2 == n;
+        }
     }
-    say join ', ', @a;          # OUTPUT: «1, 5, 42␤»
+
+    say factors(36); # OUTPUT: «1, 36, 2, 18, 3, 12, 4, 9, 6␤»
 
 C<gather/take> can generate values lazily, depending on context. If you want to
 force lazy evaluation use the L<lazy|/type/Iterable#method_lazy> subroutine or
 method. Binding to a scalar or sigilless container will also force laziness.
-
-For example
+For example:
 
     my @vals = lazy gather {
         take 1;