perlvar $1 clarification

$1 is currently documented as being set by the "last pattern match".
But it is left alone by unsuccessful pattern match attempts (continuing
to hold a value from an earlier successful match).

Saying "last successful pattern match" clarifies this; it's also the
phrase used to document $&.

Second, the entry for $1 in perlvar doesn't actually contain the text
"$1" anywhere.  As such, doing man perlvar then using /\$1 to search for
it in less doesn't locate it (though does match other places in that
file where $1 happens to be used).

diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index 7c61a05..f2e29e1 100644 (file)
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -214,11 +214,11 @@ able to use them in the sort() comparison block or function.
 
 =over 8
 
-=item $<I<digits>>
+=item $<I<digits>> ($1, $2, ...)
 X<$1> X<$2> X<$3>
 
 Contains the subpattern from the corresponding set of capturing
-parentheses from the last pattern match, not counting patterns
+parentheses from the last successful pattern match, not counting patterns
 matched in nested blocks that have been exited already.  (Mnemonic:
 like \digits.)  These variables are all read-only and dynamically
 scoped to the current BLOCK.