Elaborate on capture numbering

Author: moritz

lib/Language/regexes.pod

@@ -408,7 +408,30 @@ the capturing groups that you do care about, and it is a bit faster.
 
 =head2 Capture Numbers
 
-TODO: describe how alternations affect capturing numbers; nested captures
+The statement above that captures are numbered from left to right. While true
+in principle, it is also overly simplistic.
+
+The following rules are listed for the sake of completeness; when you find
+yourself using them regularly, it is worth considering named captures (and
+possibly subrules) instead.
+
+Alternations resets the capture count:
+
+    / (x) (y)  || (a) (.) (.) /
+    # $0  $1      $0  $1  $2
+
+Example:
+
+    if 'abc' ~~ /(x)(y) || (a)(.)(.)/ {
+        say ~$1;            # b
+    }
+
+Captures can be nested, in which case they are numbered per level
+
+    if 'abc' ~~ / ( a (.) (.) ) / {
+        say "Outer: $0";              # Outer: abc
+        say "Inner: $0[0] and $0[1]"; # Inner: b and c
+    }
 
 =head1 Adverbs