Reflow and clarifications refs #2887

Author: JJ

doc/Language/regexes.pod6

@@ -995,8 +995,8 @@ The same grouping applies to quantifiers:
     / (a b)+ /;        # matches one or more sequences of 'ab'
     / (a || b)+ /;     # matches a string of 'a's and 'b's, except empty string
 
-An unquantified capture produces a L<Match|/type/Match> object. When a capture is
-quantified (except with the C<?> quantifier) the capture becomes a list of
+An unquantified capture produces a L<Match|/type/Match> object. When a capture
+is quantified (except with the C<?> quantifier) the capture becomes a list of
 L<Match|/type/Match> objects instead.
 
 =head2 X«Capturing|regex,( )»
@@ -1043,14 +1043,14 @@ which, by default, don't capture.
 
 If you do not need the captures, using non-capturing C<[ ... ]>
 groups provides the following benefits:
-=item  they more cleanly communicate the regex intent;
-=item  they make it easier to count the capturing groups that do mean;
+=item  they more cleanly communicate the regex intent,
+=item  they make it easier to count the capturing groups that do mean and
 =item  they make matching a bit faster.
 
 =head2 Capture numbers
 
 It is stated above that captures are numbered from left to right. While true
-in principle, this is also over simplification.
+in principle, this is also an over simplification.
 
 The following rules are listed for the sake of completeness. When you find
 yourself using them regularly, it's worth considering named captures (and
@@ -1075,7 +1075,9 @@ the one with the most captures determines the index of the next capture:
         say ~$2;            # OUTPUT: «d␤»
     }
 
-Captures can be nested, in which case they are numbered per level
+Captures can be nested, in which case they are numbered per level; level 0 gets
+to use the capture variables, but it will become a list with the rest of the
+levels behaving as elements of that list
 
     if 'abc' ~~ / ( a (.) (.) ) / {
         say "Outer: $0";                # OUTPUT: Outer: abc
@@ -1085,13 +1087,15 @@ Captures can be nested, in which case they are numbered per level
 If you need to refer to a capture from within another capture, store
 it in a variable first:
 
-    # !!WRONG!! The $0 refers to a capture *inside* the second capture
-    say "11" ~~ /(\d) ($0)/; # OUTPUT: «Nil␤»
+=begin code
+# !!WRONG!! The $0 refers to a capture *inside* the second capture
+say "11" ~~ /(\d) ($0)/; # OUTPUT: «Nil␤»
 
-    # CORRECT: $0 is saved into a variable outside the second capture
-    # before it is used inside (the `{}` is needed to update the current match)
-    say "11" ~~ /(\d) {} :my $c = $0; ($c)/; # OUTPUT: «｢11｣␤ 0 => ｢1｣␤ 1 => ｢1｣␤»
-    say "Matched $c"; # OUTPUT: «␤Matched 1␤»
+# CORRECT: $0 is saved into a variable outside the second capture
+# before it is used inside (the `{}` is needed to update the current match)
+say "11" ~~ /(\d) {} :my $c = $0; ($c)/; # OUTPUT: «｢11｣␤ 0 => ｢1｣␤ 1 => ｢1｣␤»
+say "Matched $c"; # OUTPUT: «␤Matched 1␤»
+=end code
 
 
 X<|:my>
@@ -1104,7 +1108,9 @@ regex. This can be used for debugging inside regular expressions, for instance:
     say "Matched $counter lines"; # OUTPUT: «Matched 3 lines␤»
 
 X<|:our>
-The C<:our>, similarly to L<C<our>|/syntax/our> in classes, can be used in L<Grammar|/type/Grammar>s to declare variables that can be accessed, via its fully qualified name, from outside the grammar:
+The C<:our>, similarly to L<C<our>|/syntax/our> in classes, can be used in
+L<Grammar|/type/Grammar>s to declare variables that can be accessed, via its
+fully qualified name, from outside the grammar:
 
 =begin code
 grammar HasOur {