Document regex substitution adverbs

Closes #1133

Author: moritz

doc/Language/regexes.pod6

@@ -1426,6 +1426,56 @@ abracadabra
        abra
 =end code
 
+=head2 Substitution Adverbs
+
+You can apply matching adverbs (such as C<:global>, C<:pos> etc.) to
+substitutions. In addition, there are adverbs that only make sense for
+substitutions, because they transfer a property from the matched string
+to the replacement string.
+
+=head3 X<Samecase|subsitution adverb,:samecase;substitution adverb,:ii>
+
+The C<:samecase> or C<:ii> substitution adverb implies the
+C<:ignorecase> adverb for the regex part of the substitution, and in
+addition carries the case information to the replacement string:
+
+=begin code
+$_ = 'The cat chases the dog';
+s:global:samecase[the] = 'a';
+say $_;                 # OUTPUT: «A cat chases a dog»
+=end code
+
+Here you can see that the first replacement string C<a> got capitalized,
+because the first string of the matched string was also a capital
+letter.
+
+=head3 X<Samemark|subsitution adverb,:samemark;substitution adverb,:mm>
+
+The C<:samemark> or C<:mm> adverb implies C<:ignoremark> for the regex,
+and in addition, copies the markings from the matched characters to the
+replacement string:
+
+=begin code
+given 'äộñ' {
+    say S:mm/ a .+ /uia/;           # OUTPUT: «üị̂ã»
+}
+=end code
+
+=head3 X<Samespace|subsitution adverb,:samespace;substitution adverb,:ss>
+
+The C<:samespace> or C<:ss> substitution modifier implies the
+C<:sigspace> modifier for the regex, and in addition, copies the
+whitespace from the matched string to the replacement string:
+
+=begin code
+say S:samespace/a ./c d/.perl given "a b";      # OUTPUT: «"c d"»
+say S:samespace/a ./c d/.perl given "a\tb";     # OUTPUT: «"c\td"»
+say S:samespace/a ./c d/.perl given "a\nb";     # OUTPUT: «"c\nd"»
+=end code
+
+The C<ss/.../.../> syntactic form is a shorthand for
+C<s:samespace/.../.../>.
+
 =head1 Look-around assertions
 
 =head2 X<Lookahead assertions|regex,before;regex,after>