From d1dfe9ff3ad66633549ee3104b6e3a8f5269769c Mon Sep 17 00:00:00 2001
From: Karl Williamson <khw@cpan.org>
Date: Sat, 3 May 2025 20:14:24 -0600
Subject: [PATCH] perlop: Add here-doc examples

Fixes #20886
---
 pod/perlop.pod | 51 ++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 47 insertions(+), 4 deletions(-)

diff --git a/pod/perlop.pod b/pod/perlop.pod
index 0b2d144dc895..4f6e5d376bd6 100644
--- a/pod/perlop.pod
+++ b/pod/perlop.pod
@@ -2842,16 +2842,13 @@ 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<<< << >>>
+X<here-doc> X<here-docs> X<heredoc> X<here-document> X<<< << >>>
 
 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).
-
 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,
@@ -2862,6 +2859,52 @@ on the terminating line.
 If the terminating string is quoted, the type of quotes used determine
 the treatment of the text.
 
+ my $person = 'John';
+
+ print uc << "EOT";
+ Hello, $person!  
+ And the text goes on.
+ EOT
+
+This yields
+
+ HELLO, JOHN!  
+ AND THE TEXT GOES ON.
+
+The same result happens if the double quotes are omitted 
+
+ my $person = 'John';
+ print uc <<EOT;
+ Hello, $person!  
+ And the text goes on.
+ EOT
+
+ HELLO, JOHN!  
+ AND THE TEXT GOES ON.
+
+If instead, single quotes are used, we get
+
+ my $person = 'John';
+ print uc <<'EOT';
+ Hello, $person!  
+ And the text goes on.
+ EOT
+
+ HELLO, $PERSON!  
+ AND THE TEXT GOES ON.
+
+You can do fancy things like call a function with the here-document
+
+ print uc(<<EOF);
+ abc
+ EOF
+
+ ABC
+
+It is usually easier to read the code if the here-document is indented.
+Prefixing the terminating string with a C<~> specifies that you
+want to use L</Indented Here-docs> (see below).
+
 =over 4
 
 =item Double Quotes