Document :Perl5 adverb

Author: robertlemmen

doc/Language/regexes.pod6

@@ -1273,6 +1273,18 @@ Grammars provide an easy way to override what C«<.ws>» matches:
 When parsing file formats where some whitespace (for example, vertical
 whitespace) is significant, it's advisable to override C<ws>.
 
+=head3 Perl 5 compatibility adverb
+
+The B<C<:Perl5>> or B<C<:P5>> adverb switch the Regex parsing and matching
+back to the way Perl 5 regexes did behave:
+
+    so 'hello world' ~~ m:Perl5/^hello (world)/   # OUTPUT: «True␤»
+    so 'hello world' ~~ m/^hello (world)/         # OUTPUT: «False␤»
+    so 'hello world' ~~ m/^ 'hello ' ('world')/   # OUTPUT: «True␤»
+
+The regular behavior is recommended and more idiomatic in Perl 6 of course, 
+but the B<C<:Perl5>> adverb can be useful when backwards-compatibility is required.
+
 =head2 Matching adverbs
 
 In contrast to regex adverbs, which are tied to the declaration of a regex,