Expand info on Heredocs

Author: tbrowder

doc/Language/quoting.pod6

@@ -472,7 +472,7 @@ string
 END
 =end code
 
-The contents of the heredoc always begin on the next line, so you can (and
+The contents of the I<heredoc> always begin on the next line, so you can (and
 should) finish the line.
 
 =begin code :preamble<sub my-escaping-function { $^x }>
@@ -483,7 +483,7 @@ TERMINATOR
 =end code
 
 If the terminator is indented, that amount of indention is removed from the
-string literals. Therefore this heredoc
+string literals. Therefore this I<heredoc>
 
 =begin code
 say q:to/END/;
@@ -503,7 +503,7 @@ some multi line
 
 =end code
 
-Heredocs include the newline from before the terminator.
+I<Heredocs> include the newline from before the terminator.
 
 To allow interpolation of variables use the C<qq> form, but you will then have
 to escape metacharacters C<\{> as well as C<$> if it is not the sigil for a
@@ -525,6 +525,38 @@ option {
 };
 =end code
 
+Some other situations to pay attention to are innocent-looking ones
+where the text looks like a Raku expression. For example, the
+following generates an error:
+
+=begin code :lang<text>
+my $title = 'USAFA Class of 1965';
+say qq:to/HERE/;
+<a href='https://usafa-1965.org'>$title</a>
+HERE
+# Output:
+Type Str does not support associative indexing.
+  in block <unit> at here.raku line 2
+=end code
+
+The right angle bracket makes '$title' look like a hash call
+to Raku when it is actually a Str variable, hence the error message.
+The cure is to enclose the scalar with curly braces:
+
+=begin code :lang<text>
+say qq:to/HERE/;
+<a href='https://usafa-1965.org'>{$title}</a>
+HERE
+=end code
+
+Because a I<heredoc> can be very long but is stll interpreted by Raku
+as a single line, finding the source of an error can sometimes be
+difficult. One crude way to debug the error is by starting with the
+first visible line in the code and treating is as a I<heredoc> with
+that line only. Then, until you get an error, add each line in turn.
+(Creating a Raku program to do that is left as an exercise for the
+reader.)
+
 You can begin multiple Heredocs in the same line.
 
 =begin code