Merge pull request #2286 from MorayJ/regex-clarity

Clarifies capturing properties of square brackets in regex

Author: MorayJ

doc/Language/regexes.pod6

@@ -1008,7 +1008,7 @@ The parentheses in regexes perform a double role: they group the regex
 elements inside and they capture what is matched by the sub-regex inside.
 
 To get only the grouping behavior, you can use square brackets C<[ ... ]>
-instead.
+which, by default, don't capture.
 
     if 'abc' ~~ / [a||b] (c) / {
         say ~$0;                # OUTPUT: «c␤»
@@ -1103,9 +1103,16 @@ and slightly verbose, way of naming captures is like this:
         say ~$<myname>      # OUTPUT: «abc␤»
     }
 
+The square brackets in the above example, which don't usually capture, will now capture its grouping
+with the given name.
+
 The access to the named capture, C«$<myname>», is a shorthand for indexing
 the match object as a hash, in other words: C<$/{ 'myname' }> or C«$/<myname>».
 
+We can also use round brackets in the above example, but they will work exactly the same as square brackets.
+The captured group will only be accessible by its name as a key from the match object and not from
+its position in the list with C<$/[0]> or C<$0>.
+
 Named captures can also be nested using regular capture group syntax:
 
     if 'abc-abc-abc' ~~ / $<string>=( [ $<part>=[abc] ]* % '-' ) / {
@@ -1129,7 +1136,7 @@ all named captures:
         }
     }
 
-A more convenient way to get named captures is discussed in
+A more convenient way to get named captures is by using named regex as discussed in
 the L<Subrules|#Subrules> section.
 
 =head2 X«Capture markers: C«<( )>»|regex,<( )>»