Document how to use run with <>

Also slightly discourage «», and add a separate section to traps about
«». It is somewhat copypasted but that's ok, as having a separate
section in traps raises awareness without requiring to read all of the
docs.

Resolves #1745 and makes me happy.

Author: AlexDaniel

doc/Language/traps.pod6

@@ -1232,6 +1232,25 @@ The bottom line is that C<map> and C<»> are not interchangeable, but
 using one instead of the other is OK as long as you understand the
 differences.
 
+=head2 Word splitting in C<« »>
+
+Keep in mind that C<« »> performs word splitting similarly to how
+shells do it, so
+L<many shell pitfalls|http://mywiki.wooledge.org/BashPitfalls> apply
+here as well (especially when using in combination with C<run>):
+
+    my $file = ‘--my arbitrary filename’;
+    run ‘touch’, ‘--’, $file;  # RIGHT
+    run <touch -->, $file;     # RIGHT
+
+    run «touch -- "$file"»;    # RIGHT but WRONG if you forget quotes
+    run «touch -- $file»;      # WRONG; touches ‘--my’, ‘arbitrary’ and ‘filename’
+    run ‘touch’, $file;        # WRONG; error from `touch`
+    run «touch "$file"»;       # WRONG; error from `touch`
+
+Note that C<--> is required to make it work for
+L<filenames with leading dashes|http://mywiki.wooledge.org/BashPitfalls#Filenames_with_leading_dashes>.
+
 =head1 Scope
 
 =head2 Using a C<once> block

doc/Type/IO.pod6

@@ -339,8 +339,24 @@ Runs an external command without involving a shell and returns a L<Proc> object.
 
     run 'touch', '>foo.txt'; # Create a file named >foo.txt
 
-    run Q:w{rm >foo.txt}; # Another way to use run, using word quoting for the
-                          # arguments
+    run <rm >foo.txt>; # Another way to use run, using word quoting for the
+                       # arguments
+
+If you want to pass some variables you can still use C«< >», but try
+to avoid using C<« »> as it will do word splitting if you forget to
+quote variables:
+
+    my $file = ‘--my arbitrary filename’;
+    run ‘touch’, ‘--’, $file;  # RIGHT
+    run <touch -->, $file;     # RIGHT
+
+    run «touch -- "$file"»;    # RIGHT but WRONG if you forget quotes
+    run «touch -- $file»;      # WRONG; touches ‘--my’, ‘arbitrary’ and ‘filename’
+    run ‘touch’, $file;        # WRONG; error from `touch`
+    run «touch "$file"»;       # WRONG; error from `touch`
+
+Note that C<--> is required to make it work for
+L<filenames with leading dashes|http://mywiki.wooledge.org/BashPitfalls#Filenames_with_leading_dashes>.
 
 A sunk L<Proc> object for a process that L<exited|/routine/exitcode> unsuccessfully
 will throw. If you wish to ignore such failures, simply use L<run> in non-sink context: