Expand on Capture documentation

lib/Type/Capture.pod

@@ -6,24 +6,62 @@
 
     class Capture does Positonal does Associative { }
 
-A Capture is an argument list for passing it to a code object.
-It contains a list-like part for positional arguments and a hash-like part
-for named arguments.
-
-Captures can be created by prefixing a term with a backslash C<\>.
+A Capture is a container for passing arguments to a code object.  Captures
+are the flip-side of Signatures -- Captures at the caller define arguments,
+while Signatures at the callee define parameters.
+
+When you call C<print $a, $b>, the C<$a, $b> part is a Capture.
+
+Captures contain a list-like part for positional arguments and a hash-like
+part for named arguments.  For the named arguments, Captures use a slightly
+different I<syntax> than a normal List.  There are two easy ways to make a
+named argument: 1) use an unquoted key naming a parameter, followed by C<'=>'>,
+followed by the argument and 2) use a colon-pair literal named after the
+parameter:
+
+    say unique 1, -2, 2, 3, as => { abs $_ }; # 1, -2, 3
+    # ... is the same thing as:
+    say unique 1, -2, 2, 3, :as({ abs $_ });  # 1, -2, 3
+    # Be careful not to quote the name of a named parameter:
+    say unique 1, -2, 2, 3, 'as' => { abs $_ }; # 1, -2, 2, 3, "as" => { ... }
+
+A stand-alone Capture can also be made, stored, and used later.  A literal
+Capture can be created by prefixing a term with a backslash C<\>.
+Commonly, this term will be a List of terms, from which any Pair
+literal will be placed in the named part, and all other terms will be
+placed in the positional part.
 
     my $c = \42;            # Capture with one positional parts
-    $c = \(1, 2, a => 'b'); # Capture wit two positional and one named part
-
-Another common way to create a Capture is to prefix a sigilless parameter
-with a vertical bar C<|>, which packs the remainder of the argument list
+    $c = \(1, 2, a => 'b'); # Capture with two positional and one named part
+    
+To use such a Capture, you may use C<'|'> before it in a function call, and it
+will be as if the values in the Capture were passed directly to the function
+as arguments -- named arguments will be passed as named arguments and positional
+arguments will be passed as positional arguments.  You may re-use the Capture
+as many times as you want, even with different functions.
+
+    my $c = \(4,2,3);
+    reverse(|$c).say; # 3 2 4
+    sort(5,|$c).say;  # 2 3 4 5
+
+Inside a Signature, a Capture may be created by prefixing a sigilless parameter
+with a vertical bar C<|>.  This packs the remainder of the argument list
 into that parameter.
 
     f(1, 2, 3, a => 4, b => 5);
     sub f($a, |c) {
         # c  is  \(2, 3, a => 4, b => 5)
     }
 
+Note that Captures are still Lists in that they may contain variables, not just
+values:
+
+    my $b = 1;
+    my $c = \(4,2,$b,3);
+    sort(|$c).say;        # 1 2 3 4
+    $b = 6;
+    sort(|$c).say;        # 2 3 4 6
+
 =head1 Methods
 
 =head2 method list