perlop: Clean up here-doc documentation

The documentation for indented here-docs had a bunch of duplicated
concepts with the documentation of plain here-docs.

This commit melds them into a single coherent section.

Author: khwilliamson

pod/perlop.pod

@@ -2648,6 +2648,8 @@ X<tr> X<y> X<transliterate> X</c> X</d> X</s>
 
 =item C<y/I<SEARCHLIST>/I<REPLACEMENTLIST>/cdsr>
 
+=back
+
 These transliterate all occurrences of the characters found (or not found
 if the C</c> modifier is specified) in the search list with the
 positionally corresponding character in the replacement list, possibly
@@ -2875,85 +2877,153 @@ must use an C<eval()>:
 
     eval "tr/$oldlist/$newlist/, 1" or die $@;
 
-=item C<< <<I<EOF> >>
-X<here-doc> X<heredoc> X<here-document> X<<< << >>>
+=head3 Here-docs
+X<here-doc> X<here-docs> X<heredoc> X<here-document> X<<< << >>>
+
+=over 4
+
+=item C<< <<I<EOT> >>
+
+=item C<< <<~I<EOT> >>
+
+=back
 
 A line-oriented form of quoting is based on the shell "here-document"
 syntax.  Following a C<< << >> you specify a string to terminate
 the quoted material, and all lines following the current line down to
 the terminating string are the value of the item.
 
-Prefixing the terminating string with a C<~> specifies that you
-want to use L</Indented Here-docs> (see below).
+=over 4
 
-The terminating string may be either an identifier (a word), or some
-quoted text.  An unquoted identifier works like double quotes.
-There may not be a space between the C<< << >> and the identifier,
-unless the identifier is explicitly quoted.  The terminating string
-must appear by itself (unquoted and with no surrounding whitespace)
-on the terminating line.
+=item Plain Here-docs
 
-If the terminating string is quoted, the type of quotes used determine
-the treatment of the text.
+An example is
 
-=over 4
+ my $endng = <<WHIMPER;
+ This is the way the text ends.
+ This is the way the text ends.
+ Not with a bang, but with a
+ WHIMPER
 
-=item Double Quotes
+In this case, the terminator is an identifier, the word "WHIMPER".  Most
+usually, people capitalize the identifier, just so it stands out, but
+this is just a convention that isn't necessary.  There may not be a
+space between the C<< << >> and the identifier,
 
-Double quotes indicate that the text will be interpolated using exactly
-the same rules as normal double quoted strings.
+The terminator may be enclosed in quotes, as detailed below, but without
+them, the text of the here-doc acts exactly as if it were double-quoted.
 
-    print <<EOF;
-    The price is $Price.
-    EOF
+ my $person = 'John';
 
-    print << "EOF"; # same as above
-    The price is $Price.
-    EOF
+ print uc << EOT;
+ Hello, $person!
+ And the text goes on.
+ EOT
 
+This yields:
 
-=item Single Quotes
+ HELLO, JOHN!
+ AND THE TEXT GOES ON.
 
-Single quotes indicate the text is to be treated literally with no
-interpolation of its content.  This is similar to single quoted
-strings except that backslashes have no special meaning, with C<\\>
-being treated as two backslashes and not one as they would in every
-other quoting construct.
+The parentheses in the C<uc> function call don't have to be omitted:
 
-Just as in the shell, a backslashed bareword following the C<<< << >>>
-means the same thing as a single-quoted string does:
+ print uc(<<EOT);
+ Hello, $person!
+ And the text goes on.
+ EOT
 
-    $cost = <<'VISTA';  # hasta la ...
-    That'll be $10 please, ma'am.
-    VISTA
+ HELLO, JOHN!
+ AND THE TEXT GOES ON.
 
-    $cost = <<\VISTA;   # Same thing!
-    That'll be $10 please, ma'am.
-    VISTA
+And you can intermix a here-document with other things:
 
-This is the only form of quoting in perl where there is no need
-to worry about escaping content, something that code generators
-can and do make good use of.
+ print <<EOT, "Followed by the next argument\n";
+ Hello, $person!
+ And the text goes on.
+ EOT
 
-=item Backticks
+ Hello, John!
+ And the text goes on.
+ Followed by the next argument
 
-The content of the here doc is treated just as it would be if the
-string were embedded in backticks.  Thus the content is interpolated
-as though it were double quoted and then executed via the shell, with
-the results of the execution returned.
+And you can have multiple here-documents:
 
-    print << `EOC`; # execute command and get results
-    echo hi there
-    EOC
+ print <<EOT1, <<EOT2;
+ Hello, $person!
+ And the text goes on.
+ EOT1
+ Followed by the next argument
+ EOT2
 
-=back
+ Hello, John!
+ And the text goes on.
+ Followed by the next argument
 
-=over 4
+The terminator doesn't have to be a single word; it may also be some
+quoted text,
+
+ my $pagliaci = << "La Commedia e finita!";
+ On stage, the actor playing the jealous husband stabs for real the
+ actress who is both his real wife and playing the part; then he stabs
+ her lover who runs from the audience to defend her.  Both die.
+ La Commedia e finita!
+
+When the terminator is quoted, there may be space between it and the
+C<<< << >>>, as demonstrated in the example just above.  Quoting rules
+for it are unrelated to Perl's quoting rules.  C<q()>, C<qq()>, and the
+like are not supported in place of C<""> and C<''>, and the only
+interpolation is for backslashing the quoting character:
+
+    print << "abc\"def";
+    testing...
+    abc"def
+
+The terminating string must appear by itself (unquoted and with no
+surrounding whitespace) on the terminating line.  And, it cannot span
+multiple lines.  The general rule is that the identifier must be a
+string literal.  Stick with that, and you should be safe.
+
+Don't forget that you have to put a semicolon on the end to finish the
+statement, as Perl doesn't know you're not going to try to do this:
+
+    print <<ABC
+    179231
+    ABC
+       + 20;
+
+If you want to remove the line terminator from your here-docs,
+use C<chomp()>.
+
+    chomp($string = <<'END');
+    This is a string.
+    END
+
+If you use a here-doc within a delimited construct, such as in C<s///eg>,
+the quoted material must still come on the line following the
+C<<< <<FOO >>> marker, which means it may be inside the delimited
+construct:
+
+    s/this/<<E . 'that'
+    the other
+    E
+     . 'more '/eg;
+
+It works this way as of Perl 5.18.  Historically, it was inconsistent, and
+you would have to write
+
+    s/this/<<E . 'that'
+     . 'more '/eg;
+    the other
+    E
+
+outside of string evals.
 
 =item Indented Here-docs
 
-The here-doc modifier C<~> allows you to indent your here-docs to make
-the code more readable:
+A problem with the original Here-doc syntax is that it must be at the
+left margin of your program, messing up the indentation.  Starting in
+Perl v5.26, the tilde C<~> modifier allows you to indent your here-docs
+to make the code more readable.
 
     if ($some_var) {
         print <<~EOF;
@@ -2989,91 +3059,78 @@ delimiter) will be preserved:
                 This text is indented with two tabs
       EOF
 
-Finally, the modifier may be used with all of the forms
-mentioned above:
+=back
 
-    <<~\EOF;
-    <<~'EOF'
-    <<~"EOF"
-    <<~`EOF`
+If the terminating string is quoted, the type of quotes used determine
+the treatment of the text.
 
-And whitespace may be used between the C<~> and quoted delimiters:
+=over 4
 
-    <<~ 'EOF'; # ... "EOF", `EOF`
+=item Double Quotes
 
-=back
+Double quotes surrounding the terminating word or string behave as if
+no quotes were there, namely the text will be interpolated using exactly
+the same rules as normal double quoted strings, as in all the examples
+above.  So
 
-It is possible to stack multiple here-docs in a row:
+ my $person = 'John';
 
-    print <<"foo", <<"bar"; # you can stack them
-    I said foo.
-    foo
-    I said bar.
-    bar
+ print uc << "EOT";
+ Hello, $person!
+ And the text goes on.
+ EOT
 
-    myfunc(<< "THIS", 23, <<'THAT');
-    Here's a line
-    or two.
-    THIS
-    and here's another.
-    THAT
+yields:
 
-Just don't forget that you have to put a semicolon on the end
-to finish the statement, as Perl doesn't know you're not going to
-try to do this:
+ HELLO, JOHN!
+ AND THE TEXT GOES ON.
 
-    print <<ABC
-    179231
-    ABC
-       + 20;
+which is the same result as without quotes.
 
-If you want to remove the line terminator from your here-docs,
-use C<chomp()>.
+=item Single Quotes
 
-    chomp($string = <<'END');
-    This is a string.
-    END
+If instead, single quotes are used, the text is treated literally, with
+no interpolation of its content.
 
-If you want your here-docs to be indented with the rest of the code,
-use the C<<< <<~FOO >>> construct described under L</Indented Here-docs>:
+ my $person = 'John';
+ print uc <<'EOT';
+ Hello, $person!
+ And the text goes on.
+ EOT
 
-    $quote = <<~'FINIS';
-       The Road goes ever on and on,
-       down from the door where it began.
-       FINIS
+ HELLO, $PERSON!
+ AND THE TEXT GOES ON.
 
-If you use a here-doc within a delimited construct, such as in C<s///eg>,
-the quoted material must still come on the line following the
-C<<< <<FOO >>> marker, which means it may be inside the delimited
-construct:
+The difference between a single-quoted here-doc and a single-quoted
+string is that backslashes have no special meaning, with C<\\> being
+treated as two backslashes and not one as they would in every other
+quoting construct.
 
-    s/this/<<E . 'that'
-    the other
-    E
-     . 'more '/eg;
+Just as in the shell, a backslashed bareword following the C<<< << >>>
+means the same thing as a single-quoted string does:
 
-It works this way as of Perl 5.18.  Historically, it was inconsistent, and
-you would have to write
+    $cost = <<'VISTA';  # hasta la ...
+    That'll be $10 please, ma'am.
+    VISTA
 
-    s/this/<<E . 'that'
-     . 'more '/eg;
-    the other
-    E
+    $cost = <<\VISTA;   # Same thing!
+    That'll be $10 please, ma'am.
+    VISTA
 
-outside of string evals.
+These two forms are the only ways of quoting in perl where there is no
+need to worry about escaping content, something that code generators can
+and do make good use of.
 
-Additionally, quoting rules for the end-of-string identifier are
-unrelated to Perl's quoting rules.  C<q()>, C<qq()>, and the like are not
-supported in place of C<''> and C<"">, and the only interpolation is for
-backslashing the quoting character:
+=item Backticks
 
-    print << "abc\"def";
-    testing...
-    abc"def
+The content of the here doc is treated just as it would be if the
+string were embedded in backticks.  Thus the content is interpolated
+as though it were double quoted and then executed via the shell, with
+the results of the execution returned.
 
-Finally, quoted strings cannot span multiple lines.  The general rule is
-that the identifier must be a string literal.  Stick with that, and you
-should be safe.
+    print << `EOC`; # execute command and get results
+    echo hi there
+    EOC
 
 =back