Revising Str.match, subst and subst-mutate.

* All match adverbs and cases are mentioned.
* All subst adverbs are also mentioned in its own place. I have
  changed the ordering of the sections.
* subst-mutate is linked from subst.

So I would say the concerns of #919 have been adressed. Closes #919.

(some minor reflow in this and faq file too)

Author: JJ

doc/Language/faq.pod6

@@ -736,7 +736,9 @@ them offer all.
 
 =item Phasers (like BEGIN / END) allow code to be executed at scope entry / exit, loop first / last / next and many more special contexts.
 
-=item High level concurrency model, both for implicit as well as explicit multi-processing, which goes way beyond primitive threads and locks. Perl 6's concurrency offers a rich set of (composable) tools.
+=item High level concurrency model, both for implicit as well as explicit
+multi-processing, which goes way beyond primitive threads and locks. Perl 6's
+concurrency offers a rich set of (composable) tools.
 
 =item Multiple-core computers are getting used more and more, and with Perl 6
 these can be used thanks to parallelism, both implicit (e.g., with the C«>>».
@@ -757,11 +759,14 @@ Fibonacci sequence, or all prime numbers.
 
 =item Native data types for faster, closer to the metal, processing.
 
-=item Interfacing to external libraries in C / C++ are trivially simple with NativeCall.
+=item Interfacing to external libraries in C / C++ are trivially simple with
+NativeCall.
 
-=item Interfacing with Perl 5 (CPAN) / Python modules trivially simple with Inline::Perl5 and Inline::Python.
+=item Interfacing with Perl 5 (CPAN) / Python modules trivially simple with
+Inline::Perl5 and Inline::Python.
 
-=item Can have multiple versions of a module installed and loaded simultaneously.
+=item Can have multiple versions of a module installed and loaded
+simultaneously.
 
 =item System administration simplified due to simpler update/upgrade policies.
 

doc/Type/Str.pod6

@@ -186,34 +186,40 @@ after the previous match.
 
     method match($pat, :continue(:$c), :pos(:$p), :global(:$g), :overlap(:$ov), :exhaustive(:$ex), :st(:$nd), :rd(:$th), :$nth, :$x --> Match)
 
-Performs a match of the string against C<$pat> and returns a L<Match> object if there is a successful match,
-and C<(Any)> otherwise. Matches are stored in C<$/>. If C<$pat> is not a L<Regex> object, match will coerce
-the argument to a Str and then perform a literal match against C<$pat>.
+Performs a match of the string against C<$pat> and returns a L<Match> object if
+there is a successful match; it returns C<(Any)> otherwise. Matches are stored in the
+L<default match variable C<$/>|/language/variables#index-entry-match_variable>.
+If C<$pat> is not a L<Regex> object, match will coerce the argument to a
+Str and then perform a literal match against C<$pat>.
 
 A number of optional named parameters can be specified, which alter how the match is performed.
 
 =item :continue
 
-The C<:continue> adverb takes as an argument the position where the regex should start to search.
-If no position is specified for C<:c> it will default to 0 unless C<$/> is set, in which case it defaults to C<$/.to>.
+The C<:continue> adverb takes as an argument the position where the regex should
+start to search. If no position is specified for C<:c> it will default to 0
+unless C<$/> is set, in which case it defaults to C<$/.to>.
 
 =item :pos
 
 Takes a position as an argument. Fails if regex cannot be matched from that position, unlike C<:continue>.
 
 =item :global
 
-Instead of searching for just one match and returning a C<Match> object, search for every non-overlapping match and return them in a C<List>.
+Instead of searching for just one match and returning a C<Match> object, search
+for every non-overlapping match and return them in a C<List>.
 
 =item :overlap
 
-Finds all matches including overlapping matches, but only returns one match from each starting position.
+Finds all matches including overlapping matches, but only returns one match from
+each starting position.
 
 =item :exhaustive
 
-Finds all possible matches of a regex, including overlapping matches and matches that start at the same position.
+Finds all possible matches of a regex, including overlapping matches and matches
+that start at the same position.
 
-=item :st, :nd, rd, nth
+=item :st, :nd, :rd, :nth
 
 Returns the nth match in the string. The argument can be a L<Numeric> or
 an L<Iterable> producing monotonically increasing numbers (that is, the
@@ -226,9 +232,10 @@ will be set to a possibly-empty L<List> of L<Match> objects.
 
 =item :x
 
-Takes as an argument the number of matches to return, stopping once the specified number of matches has been reached. The value must be a L<Numeric>
-or a L<Range>; other values will cause C<.match> to return a L<Failure>
-containing C<X::Str::Match::x> exception.
+Takes as an argument the number of matches to return, stopping once the
+specified number of matches has been reached. The value must be a L<Numeric> or
+a L<Range>; other values will cause C<.match> to return a L<Failure> containing
+C<X::Str::Match::x> exception.
 
 Examples:
 =begin code
@@ -843,8 +850,11 @@ Returns C<True> if the invocant is identical to or ends with C<$needle>.
 Returns the invocant string where C<$matcher> is replaced by C<$replacement>
 (or the original string, if no match was found).
 
-There is an in-place syntactic variant of C<subst> spelled L«C<s/matcher/replacement/>|/syntax/s$SOLIDUS%20$SOLIDUS%20$SOLIDUS»
-as well as the L«C<.subst-mutate> method|/routine/subst-mutate».
+There is an in-place syntactic variant of C<subst> spelled
+L«C<s/matcher/replacement/>|/syntax/s$SOLIDUS%20$SOLIDUS%20$SOLIDUS» and with
+adverb following the C<s> or inside the matcher,  as well as the
+L«C<.subst-mutate> method|/routine/subst-mutate» which modifies the string
+in-place.
 
 C<$matcher> can be a L<Regex>, or a literal C<Str>. Non-Str matcher arguments
 of type L<Cool> are coerced to C<Str> for literal matching.
@@ -861,10 +871,10 @@ multi-match options like C<:g> are used).
 
 =head3 Callable
 
-The replacement can be a L<Callable> in which the current L<Match> object will be
-placed in the C<$/> variable, as well as the C<$_> topic variable.
-Using a L<Callable> as replacement is how you can refer to any of the captures
-created in the regex:
+The replacement can be a L<Callable> in which the current L<Match> object will
+be placed in the C<$/> variable, as well as the C<$_> topic variable. Using a
+L<Callable> as replacement is how you can refer to any of the captures created
+in the regex:
 
     # Using capture from $/ variable (the $0 is the first positional capture)
     say 'abc123defg'.subst(/(\d+)/, { " before $0 after " });
@@ -884,25 +894,6 @@ created in the regex:
     say $str.subst(/secret/, {++$i}); # The answer to everything
     # OUTPUT: «The answer is 42.␤»
 
-=head3 More Examples
-
-Here are other examples of usage:
-
-    my $str = "Hey foo foo foo";
-    $str.subst(/foo/, "bar", :g); # global substitution - returns Hey bar bar bar
-
-    $str.subst(/foo/, "no subst", :x(0)); # targeted substitution. Number of times to substitute. Returns back unmodified.
-    $str.subst(/foo/, "bar", :x(1)); #replace just the first occurrence.
-
-    $str.subst(/foo/, "bar", :nth(3)); # replace nth match alone. Replaces the third foo. Returns Hey foo foo bar
-
-The C<:nth> adverb has readable English-looking variants:
-
-    say 'ooooo'.subst: 'o', 'x', :1st; # OUTPUT: «xoooo␤»
-    say 'ooooo'.subst: 'o', 'x', :2nd; # OUTPUT: «oxooo␤»
-    say 'ooooo'.subst: 'o', 'x', :3rd; # OUTPUT: «ooxoo␤»
-    say 'ooooo'.subst: 'o', 'x', :4th; # OUTPUT: «oooxo␤»
-
 =head3 Adverbs
 
 The following adverbs are supported
@@ -924,6 +915,27 @@ Note that only in the C<s///> form C<:ii> implies C<:i> and C<:ss> implies
 C<:s>. In the method form, the C<:s> and C<:i> modifiers must be added to the
 regex, not the C<subst> method call.
 
+
+=head3 More Examples
+
+Here are other examples of usage:
+
+    my $str = "Hey foo foo foo";
+    $str.subst(/foo/, "bar", :g); # global substitution - returns Hey bar bar bar
+
+    $str.subst(/foo/, "no subst", :x(0)); # targeted substitution. Number of times to substitute. Returns back unmodified.
+    $str.subst(/foo/, "bar", :x(1)); #replace just the first occurrence.
+
+    $str.subst(/foo/, "bar", :nth(3)); # replace nth match alone. Replaces the third foo. Returns Hey foo foo bar
+
+The C<:nth> adverb has readable English-looking variants:
+
+    say 'ooooo'.subst: 'o', 'x', :1st; # OUTPUT: «xoooo␤»
+    say 'ooooo'.subst: 'o', 'x', :2nd; # OUTPUT: «oxooo␤»
+    say 'ooooo'.subst: 'o', 'x', :3rd; # OUTPUT: «ooxoo␤»
+    say 'ooooo'.subst: 'o', 'x', :4th; # OUTPUT: «oooxo␤»
+
+
 =head2 method subst-mutate
 
 Where L<subst> returns the modified string and leaves the original