Add ^ twigil to traps. Fixes #364 (#964)

This commit adds documentation to help clarify troubles with the ^ twigil.

Author: nicqrocks

doc/Language/traps.pod6

@@ -445,6 +445,32 @@ throws. Explicitly sinking it inside the C<try> avoids the issue:
     say "still alive";
     # OUTPUT: still alive
 
+=head1 Using Shortcuts
+
+=head2 The ^ twigil
+
+Using the C<^> twigil can save a fair amount of time and space when writing out small blocks of code. As an example:
+
+    for 1..8 -> $a, $b { say $a + $b; }
+
+can be shortened to just
+
+    for 1..8 { say $^a + $^b; }
+
+The trouble arises when a person wants to use more complex names for the variables, instead of just one letter. The C<^> twigil is able to have the positional variables be out of order and named whatever you want, but assigns values based on the variable's Unicode ordering. In the above example, we can have C<$^a> and C<$^b> switch places, and those variables will keep their positional values. This is beacuse the Unicode character 'a' comes before the character 'b'. For example:
+
+    #In order
+    sub f1 { say "$^first $^second"; }
+    f1 "Hello", "there";    #"Hello There"
+
+    #Out of order
+    sub f2 { say "$^second $^first"; }
+    f2 "Hello", "there";    #"there Hello"
+
+Due to the variables allowed to be called anything, this can cause some problems if you are not accustomed to how Perl6 handles these variables.
+
+    for 1..4 { say "$^one $^two $^three $^four"; }    # 2 4 3 1
+
 =end pod
 
 # vim: expandtab shiftwidth=4 ft=perl6