Assuming v-strings deprecation proceeds as planned,

here are some more doc changes.

p4raw-id: //depot/maint-5.8/perl@20472

5 files changed, 56 insertions, 41 deletions

diff --git a/pod/perldata.pod b/pod/perldata.pod
index 027b00e823..a41a74dcaa 100644
--- a/pod/perldata.pod
+++ b/pod/perldata.pod
@@ -339,10 +339,18 @@ an expression.
 
 =head3 Version Strings
 
-B<Note:> Version Strings (v-strings) have been deprecated.  They will
-be removed in some future release after Perl 5.8.1.  The marginal
-benefits of v-strings were greatly outweighed by the potential for
-Surprise and Confusion.
+B<NOTE:> Version strings (v-strings) have been deprecated in Perl
+5.8.1.  Version strings will be removed in some future release after
+Perl 5.8.1.  The marginal benefits of v-strings were greatly
+outweighed by the potential for Surprise and Confusion.
+
+Even the best case for their use, being used as version numbers for
+Perl itself and modules, was not backwards compatible to Perl versions
+earlier than 5.6.0.
+
+If you are using literal v-strings or the C<$^V> variable for version
+comparison, please use either the old numerical way (5.00801
+for Perl 5.8.1, for example) and the variable C<$[> instead.
 
 A literal of the form C<v1.20.300.4000> is parsed as a string composed
 of characters with the specified ordinals.  This form, known as
@@ -368,8 +376,6 @@ are not v-strings before the C<< => >> operator (which is usually used
 to separate a hash key from a hash value), instead they are interpreted
 as literal strings ('v65').  They were v-strings from Perl 5.6.0 to
 Perl 5.8.0, but that caused more confusion and breakage than good.
-Multi-number v-strings like C<v65.66> and C<65.66.67> continue to
-be v-strings always.
 
 =head3 Special Literals
 
diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index fceadc00a1..f00a06ba3e 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -213,6 +213,11 @@ see the deprecation warnings, use:
 
     no warnings 'deprecated';
 
+Similarly, prefer the old way of using the C<$]> variable and numeric
+comparisons instead of the C<$^V> variable.  The C<$^V> and v-strings
+in general never did work for pre-5.6.0 Perls, so they weren't that
+great for version compatibility checks to begin with.
+
 =head3 (Reminder) Pseudo-hashes are deprecated (really)
 
 Pseudo-hashes were deprecated in Perl 5.8.0 and will be removed in
@@ -666,6 +671,7 @@ Something modified the values being iterated over.  This is not good.
 
 The marginal benefits of v-strings were greatly outweighed by the
 potential for Surprise and Confusion.
+See L<perldata/"Version Strings"> for more information.
 
 =head1 Changed Internals
 
diff --git a/pod/perldiag.pod b/pod/perldiag.pod
index 2af70c7445..14f287fa10 100644
--- a/pod/perldiag.pod
+++ b/pod/perldiag.pod
@@ -4432,7 +4432,8 @@ minimum version.
 =item v-strings are deprecated
 
 (D deprecated) v-strings are deprecated.  Their semantics and use were
-overly confusing.
+found to be overly confusing and error-prone.
+See L<perldata/"Version Strings"> for more information.
 
 =item Warning: something's wrong
 
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index b342cf5600..71b7f1e316 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -4016,20 +4016,19 @@ rename(2) manpage or equivalent system documentation for details.
 Demands a version of Perl specified by VERSION, or demands some semantics
 specified by EXPR or by C<$_> if EXPR is not supplied.
 
-VERSION may be either a numeric argument such as 5.006, which will be
-compared to C<$]>, or a literal of the form v5.6.1, which will be compared
-to C<$^V> (aka $PERL_VERSION).  A fatal error is produced at run time if
-VERSION is greater than the version of the current Perl interpreter.
-Compare with L</use>, which can do a similar check at compile time.
+VERSION will be compared to C<$]>.  A fatal error is produced at run
+time if VERSION is greater than the version of the current Perl
+interpreter.  Compare with L</use>, which can do a similar check at
+compile time.
 
-Specifying VERSION as a literal of the form v5.6.1 should generally be
-avoided, because it leads to misleading error messages under earlier
-versions of Perl which do not support this syntax.  The equivalent numeric
-version should be used instead.
+    require 5.006;	# run time version check for Perl 5.6.0
+    require 5.006_001;	# ditto for 5.6.1
 
-    require v5.6.1;	# run time version check
-    require 5.6.1;	# ditto
-    require 5.006_001;	# ditto; preferred for backwards compatibility
+The alternate way of specifying VERSION (introduced in Perl 5.6.0)
+as a literal of the form v5.6.1 should generally be avoided, because
+it leads to misleading error messages under earlier versions of Perl
+which do not support this syntax.  The equivalent numeric version
+should be used instead.
 
 Otherwise, demands that a library file be included if it hasn't already
 been included.  The file is included via the do-FILE mechanism, which is
@@ -5031,7 +5030,7 @@ of integers, one for each character in the string, separated by
 a given string (a dot C<.> by default). This can be useful for
 displaying ordinal values of characters in arbitrary strings:
 
-  printf "version is v%vd\n", $^V;     # Perl's version
+  printf "version is v%vd\n", $^V;     # Perl's version (deprecated)
 
 Put an asterisk C<*> before the C<v> to override the string to
 use to separate the numbers:
@@ -6131,28 +6130,26 @@ package.  It is exactly equivalent to
 
 except that Module I<must> be a bareword.
 
-VERSION may be either a numeric argument such as 5.006, which will be
-compared to C<$]>, or a literal of the form v5.6.1, which will be compared
-to C<$^V> (aka $PERL_VERSION.  A fatal error is produced if VERSION is
-greater than the version of the current Perl interpreter; Perl will not
-attempt to parse the rest of the file.  Compare with L</require>, which can
-do a similar check at run time.
+VERSION will be compared to C<$]>.  A fatal error is produced if
+VERSION is greater than the version of the current Perl interpreter;
+Perl will not attempt to parse the rest of the file.  Compare with
+L</require>, which can do a similar check at run time.
 
-Specifying VERSION as a literal of the form v5.6.1 should generally be
-avoided, because it leads to misleading error messages under earlier
-versions of Perl which do not support this syntax.  The equivalent numeric
-version should be used instead.
-
-    use v5.6.1;		# compile time version check
-    use 5.6.1;		# ditto
-    use 5.006_001;	# ditto; preferred for backwards compatibility
+    use 5.006;		# compile time version check for Perl 5.6.0
+    use 5.006_001;	# ditto for Perl 5.6.1
 
 This is often useful if you need to check the current Perl version before
 C<use>ing library modules that have changed in incompatible ways from
 older versions of Perl.  (We try not to do this more than we have to.)
 
-The C<BEGIN> forces the C<require> and C<import> to happen at compile time.  The
-C<require> makes sure the module is loaded into memory if it hasn't been
+The alternate way of specifying VERSION (introduced in Perl 5.6.0)
+as a literal of the form v5.6.1 should generally be avoided, because
+it leads to misleading error messages under earlier versions of Perl
+which do not support this syntax.  The equivalent numeric version
+should be used instead.
+
+The C<BEGIN> forces the C<require> and C<import> to happen at compile time.
+The C<require> makes sure the module is loaded into memory if it hasn't been
 yet.  The C<import> is not a builtin--it's just an ordinary static method
 call into the C<Module> package to tell the module to import the list of
 features back into the current package.  The module can implement its
diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index 4ed8311d74..0749c39a70 100644
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -919,10 +919,6 @@ of perl in the right bracket?)  Example:
 See also the documentation of C<use VERSION> and C<require VERSION>
 for a convenient way to fail if the running Perl interpreter is too old.
 
-The floating point representation can sometimes lead to inaccurate
-numeric comparisons.  See C<$^V> for a more modern representation of
-the Perl version that allows accurate string comparisons.
-
 =item $COMPILING
 
 =item $^C
@@ -1153,6 +1149,15 @@ and is thereafter read-only.
 
 =item $^V
 
+B<NOTE: Version Strings (v-strings) have been deprecated in Perl 5.8.1.
+Version strings will be removed in some future release after Perl 5.8.1.
+The C<$^V> was implemented using v-strings, and therefore its future
+is uncertain.  Please refrain from using the C<$^V> and use the C<$]>
+instead.>
+
+(The following explanation describes the situation as it used to be
+for Perls starting from 5.6.0 up to and including 5.8.0.)
+
 The revision, version, and subversion of the Perl interpreter, represented
 as a string composed of characters with those ordinals.  Thus in Perl v5.6.0
 it equals C<chr(5) . chr(6) . chr(0)> and will return true for
@@ -1173,7 +1178,7 @@ C<"%vd"> conversion:
 See the documentation of C<use VERSION> and C<require VERSION>
 for a convenient way to fail if the running Perl interpreter is too old.
 
-See also C<$]> for an older representation of the Perl version.
+See also C<$]>.
 
 =item $WARNING