Be more precise in the wording of how // works.

See the discussion starting with mail:9879.1315954489@chthon
This rephrasing should avoid people getting the impression // is a
source filter, translating 'A // B' into 'defined(A) ? A : B', and
reparsing the result.

1 files changed, 7 insertions, 5 deletions

diff --git a/pod/perlop.pod b/pod/perlop.pod
index 61fd2ef448..695ec3db39 100644
--- a/pod/perlop.pod
+++ b/pod/perlop.pod
@@ -514,11 +514,13 @@ X<//> X<operator, logical, defined-or>
 
 Although it has no direct equivalent in C, Perl's C<//> operator is related
 to its C-style or.  In fact, it's exactly the same as C<||>, except that it
-tests the left hand side's definedness instead of its truth.  Thus, C<$a // $b>
-is similar to C<defined($a) || $b> (except that it returns the value of C<$a>
-rather than the value of C<defined($a)>) and yields the same result as
-C<defined($a) ? $a : $b> (except that the ternary-operator form can be
-used as a lvalue, while C<$a // $b> cannot).  This is very useful for
+tests the left hand side's definedness instead of its truth.  Thus,
+C<< EXPR1 // EXPR2 >> returns the value of C<< EXPR1 >> if it's defined,
+otherwise, the value of C<< EXPR2 >> is returned. (C<< EXPR1 >> is evaluated
+in scalar context, C<< EXPR2 >> in the context of C<< // >> itself). Usually,
+this is the same result as C<< defined(EXPR1) ? EXPR1 : EXPR2 >> (except that
+the ternary-operator form can be used as a lvalue, while C<< EXPR1 // EXPR2 >>
+cannot). This is very useful for
 providing default values for variables.  If you actually want to test if
 at least one of C<$a> and C<$b> is defined, use C<defined($a // $b)>.