Some additions to quoting.pod

lib/Language/quoting.pod

@@ -14,43 +14,114 @@ is C<'…'> or C<"…">, described in more detail in the next sections.
 
 =head2 Literal strings: Q
 
-    Q[A literal string]
-    ｢More plainly.｣
-    Q ^Almost any non-word character can be a delimiter!^
+=for code :allow<B>
+B<Q[>A literal stringB<]>
+B<｢>More plainly.B<｣>
+B<Q ^>Almost any non-word character can be a delimiter!B<^>
 
 Delimiters can nested, but in the plain C<Q> form, backslash escapes
 aren't allowed.  In other words, basic C<Q> strings are as literal as
 possible.
 
-    Q<Make sure you <match> opening and closing delimiters>
-    Q{This is still a closing brace → \}
+=for code :allow<B>
+Q<Make sure you B«<»matchB«>» opening and closing delimiters>
+Q{This is still a closing brace → B<\>}
+
+These examples produce:
+
+    A literal string
+    More plainly.
+    Almost any non-word character can be a delimiter!
+    Make sure you <match> opening and closing delimiters
+    This is still a closing brace → \
 
 The other quote forms add on to this basic functionality:
 
 =head2 Escaping: q
 
-    'Very plain'
-    q[This back\slash stays]
-    q[This back\\slash stays] # Identical output
-    Q :q $ There're no backslashes here, only lots of \$\$\$! $
-    '(Just kidding. There\'s no money in that string)'
-    'No $interpolation {here}!'
+=for code :allow<B>
+B<'>Very plainB<'>
+B<q[>This backB<\s>lash staysB<]>
+B<q[>This backB<\\>slash staysB<]> # Identical output
+B<q{>This is not a closing brace → B<\}>, but this is → B<}>
+B<Q :q $>There're no backslashes here, only lots of B<\$>B<\$>B<\$>!B<$>
+B<'>(Just kidding. ThereB<\'>s no money in that string)B<'>
+B<'>No $interpolation {here}!B<'>
+B<Q:q#>Just a literal "\n" hereB<#>
 
 The C<q> form allows for escaping characters that would otherwise end
 the string using a backslash. The backslash itself can be escaped, too,
 as in the third example above. The usual form is C<'…'> or C<q> followed
 by a delimiter, but it's also available as an adverb on C<Q>, as in the
-fourth example above.
+fifth and last example above.
+
+These examples produce:
+
+    Very plain
+    This back\slash stays
+    This back\slash stays
+    This is not a closing brace → } but this is →
+    There's no backslashes here, only lots of $$$!
+    (Just kidding. There's no money in that string)
+    No $interpolation {here}!
+    Just a literal "\n" here
 
 =head2 Interpolation: qq
 
-TODO
+=for code :allow<B L>
+my $color = 'blue';
+L<say> B<">My favorite color is B<$color>!B<">
+
+    My favorite color is blue!
+
+The C<qq> form, usually written using double quotes, allows for
+interpolation of variables, i.e, they allow you to write variables
+within the string, so that the content of the variable gets added to the
+string. C<qq> also allows escaping of these variables:
+
+=for code :allow<B>
+say B<">The B<\>$color variable contains the value '$color'B<">;
+
+    The $color variable contatins the value 'blue'
+
+Another feature of C<qq> is the ability to interpolate Perl 6 code from
+within the string, using curly braces:
+
+=for code :allow<B L>
+my ($x, $y, $z) = 4, 3.5, 3;
+say "This room is B<$x> m by B<$y> m by B<$z> m."
+say "That means its volume should be B<{ $x * $y * $z }> m³!"
+
+    This room is 4 m by 3.5 m by 3 m.
+    That means its volume should be 42 m³!
+
+By default, only variables with the C<$> sigil are interpolated
+normally. This way, when you write C<"documentation@perl6.org">, you
+aren't interpolating the C<@perl6> variable. If that's what you want to
+do, append a C<[]> to the variable name:
+
+=for code :allow<B>
+my @neighbors = "Felix", "Danielle", "Lucinda";
+say "@neighborsB<[]> and I try our best to coexist peacefully."
+
+    Felix Danielle Lucinda and I try our best to coexist peacefully.
+
+Often, though a method call is more appropriate, and these are also
+allowed within C<qq> quotes, as long as they have parentheses after the
+call. This means that C<"@example.com"> produces C<@example.com>, but
+that the following will work:
+
+=for code :allow<B L>
+say "@neighborsB<.L<join>(', ')>, and I try our best to coexist peacefully."
+
+    Felix, Danielle, Lucinda, and I try our best to coexist peacefully.
 
 =head2 Word quoting: qw
 
-    <a b c> eqv ('a', 'b', 'c')
-    qw|! @ # $ % ^ & * \| < > | eqv '! @ # $ % ^ & | < >'.words
-    Q:w { [ ] \{ \} } eqv ('[', ']', '{', '}')
+=for code :allow<B L>
+B«<»a b cB«>» L<eqv> ('a', 'b', 'c')
+B<qw|>! @ # $ % ^ & * \| < > B<|> eqv '! @ # $ % ^ & | < >'.words
+B<Q:w {> [ ] \{ \} B<}> eqv ('[', ']', '{', '}')
 
 The C<:w> form, usually written C«<…>» or C<qw>. It splits up the string into
 words (which are, in this context, defined as sequences of non-whitespace
@@ -59,6 +130,15 @@ interpolation and escape semantics of the C<q> and single quote string
 delimiters, C<Qw> and C<Q:w> inherit the non-escaping semantis of the C<Q>
 quoter.
 
+This form is used in preference to writing out many quotation marks and
+commas for lists of strings. For example, where you could write:
+
+    my @directions = 'left', 'right,', 'up', 'down';
+
+It's easier to write and to read this:
+
+    my @directions = <left right up down>;
+
 =head2 Shell quoting: qqw
 
 TODO