Indexes flattening semicolon

Also adds examples. Closes #2379.

Author: JJ

doc/Language/subscripts.pod6

@@ -339,7 +339,10 @@ elements and dimensions.
     say @twodim[0,1;1]; # 2nd element of both lists
     # OUTPUT: «(b 2)␤»
 
-Multidimensional subscripts can be used to flatten nested lists.
+X<|; (flattening)>
+
+Multidimensional subscripts can be used to flatten nested lists when combined
+with L<Whatever>.
 
     my @toomany = [[<a b>], [1, 2]];
     say @toomany;
@@ -348,6 +351,16 @@ Multidimensional subscripts can be used to flatten nested lists.
     say @toomany[*;*];
     # OUTPUT: «(a b 1 2)␤»
 
+You can use as many I<flattening semicolons> as you want; there will be, at
+most, as many nesting levels flattened as the number of semicolons:
+
+    say [[1,2,[3,4]],[4,5]][*;*];     # OUTPUT: «(1 2 [3 4] 4 5)␤»
+    say [[1,2,[3,4]],[4,5]][*;*;*;*]; # OUTPUT: «(1 2 3 4 4 5)␤»
+
+In the first example, with one C<Whatever> less than the number of levels, the
+deepest one will not be flattened; in the second case it is, since it's greater
+than the number of levels.
+
 You can use L<Whatever|/type/Whatever> to select ranges or "rows" in
 multidimensional subscripts.