Merge pull request #1640 from perl6/W4anD0eR96-patch-1

Rewrite the document of Longest Alternation: C<|>

Author: tisonkun

doc/Language/regexes.pod6

@@ -512,10 +512,46 @@ string of non-whitespace characters.
 
 =head1 X<Longest Alternation: C<|>|regex,|>
 
-In regexes branches separated by C<|>, the longest match wins, independent of
-the lexical ordering in the regexes.
+In short, in regexes branches separated by C<|>, the longest token match wins,
+independent of the textual ordering in the regexes. However, what C<|> really
+does is more than that.
 
-    say ('abc' ~~ / a | .b /).Str;    # OUTPUT: «ab␤»
+C<|> does not decide which branch to win after finishing the whole match,
+but follows the L<longest token match, for short, LTM|
+https://design.perl6.org/S05.html#Longest-token_matching> strategy.
+
+Briefly, what C<|> does is this:
+
+=item1 First, select the branch which has the longest declarative prefix.
+
+    say "abc" ~~ /ab | a.* /;                 # Output: ⌜abc⌟
+    say "abc" ~~ /ab | a {} .* /;             # Output: ⌜ab⌟
+    say "if else" ~~ / if | if <.ws> else /;  # Output: ｢if｣
+    say "if else" ~~ / if | if \s+   else /;  # Output: ｢if else｣
+
+As is shown above, C<a.*> is a declarative prefix, while C<a {} .*> terminates
+at C<{}>, then its declarative prefix is C<a>. Note that non-declarative atoms
+terminate declarative prefix. This is quite important if you want to apply
+C<|> in a C<rule>, which automatically enables C<:s>, and C«<.ws>» accidentally
+terminates declarative prefix.
+
+=item1 If it's a tie, select the match with the highest specificity.
+
+    say "abc" ~~ /a. | ab { print "win" } /;  # Output: win｢ab｣
+
+When two alternatives match at the same length, the tie is broken by
+specificity. That is, C<ab>, as an exact match, counts as closer than C<a.>,
+which uses character classes.
+
+=item1 If it's still a tie, use additional tie-breakers.
+
+    say "abc" ~~ /a\w| a. { print "lose" } /; # Output: ⌜ab⌟
+
+If the tie breaker above doesn't work, then the textually earlier alternative
+takes precedence.
+
+For more details, see
+L<the LTM strategy|https://design.perl6.org/S05.html#Longest-token_matching>.
 
 =head1 X<Conjunction: C<&&>|regex,&&>