remove dual-valueness of v-strings (i.e., they are pure strings

now); avoid the word "tuple" to describe strings represented as
character ordinals; usurp $PERL_VERSION for $^V as suggested by
Larry, deprecate $] ; adjust the documentation and testsuite
accordingly

p4raw-id: //depot/perl@5186

4 files changed, 103 insertions, 74 deletions

diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index ab025d9415..f11623b7da 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -57,6 +57,33 @@ cases remains unchanged:
 
 See L<perldata>.
 
+=head2 Perl's version numbering has changed
+
+Beginning with Perl version 5.6, the version number convention has been
+changed to a "dotted integer" scheme that is more commonly found in open
+source projects.
+
+Maintenance versions of v5.6.0 will be released as v5.6.1, v5.6.2 etc.
+The next development series following v5.6 will be numbered v5.7.x,
+beginning with v5.7.0, and the next major production release following
+v5.6 will be v5.8.
+
+The English module now sets $PERL_VERSION to $^V (a string value) rather
+than C<$]> (a numeric value).  (This is a potential incompatibility.
+Send us a report via perlbug if you are affected by this.)
+
+The v1.2.3 syntax is also now legal in Perl.
+See L<Support for strings represented as a vector of ordinals> for more on that.
+
+To cope with the new versioning system's use of at least three significant
+digits for each version component, the method used for incrementing the
+subversion number has also changed slightly.  We assume that versions older
+than v5.6 have been incrementing the subversion component in multiples of
+10.  Versions after v5.6.0 will increment them by 1.  Thus, using the new
+notation, 5.005_03 is the same as v5.5.30, and the first maintenance
+version following v5.6.0 will be v5.6.1, which amounts to a floating point
+value of 5.006_001).
+
 =item Possibly changed pseudo-random number generator
 
 In 5.005_0x and earlier, perl's rand() function used the C library
@@ -286,29 +313,6 @@ create new threads from Perl (i.e., C<use Thread;> will not work with
 interpreter threads).  C<use Thread;> continues to be available when you
 ask for -Duse5005threads, bugs and all.
 
-=head2 Perl's version numbering has changed
-
-Beginning with Perl version 5.6, the version number convention has been
-changed to a "dotted tuple" scheme that is more commonly found in open
-source projects.
-
-Maintenance versions of v5.6.0 will be released as v5.6.1, v5.6.2 etc.
-The next development series following v5.6 will be numbered v5.7.x,
-beginning with v5.7.0, and the next major production release following
-v5.6 will be v5.8.
-
-The v1.2.3 syntax is also now legal in Perl.  See L<Support for version tuples>
-for more on that.
-
-To cope with the new versioning system's use of at least three significant
-digits for each version component, the method used for incrementing the
-subversion number has also changed slightly.  We assume that versions older
-than v5.6 have been incrementing the subversion component in multiples of
-10.  Versions after v5.6 will increment them by 1.  Thus, using the new
-notation, 5.005_03 is the same as v5.5.30, and the first maintenance
-version following v5.6 will be v5.6.1, which amounts to a floating point
-value of 5.006_001).
-
 =head2 New Configure flags
 
 The following new flags may be enabled on the Configure command line
@@ -455,39 +459,43 @@ mostly useful as an alternative to the C<vars> pragma, but also provides
 the opportunity to introduce typing and other attributes for such
 variables.  See L<perlfunc/our>.
 
-=head2 Support for version tuples
+=head2 Support for strings represented as a vector of ordinals
 
-Literals of the form v1.2.3.4 are now parsed as the utf8 string
-C<"\x{1}\x{2}\x{3}\x{4}">.  This allows comparing version numbers using
-regular string comparison operators C<eq>, C<ne>, C<lt>, C<gt> etc.
+Literals of the form v1.2.3.4 are now parsed as a string comprised of
+of characters with the specified ordinals.  This is an alternative, more
+readable way to construct (possibly unicode) strings instead of
+interpolating characters, as in C<"\x{1}\x{2}\x{3}\x{4}">.
 
-These "dotted tuples" are dual-valued.  They are both strings of utf8
-characters, and floating point numbers.  Thus v1.2.3.4 has the string
-value C<"\x{1}\x{2}\x{3}\x{4}"> and the numeric value 1.002_003_004.
-As another example, v5.5.640 has the string value C<"\x{5}\x{5}\x{280}">
-(remember 280 hexadecimal is 640 decimal) and the numeric value
-5.005_64.
+Strings written in this form are also useful to represent version "numbers".
+It is easy to compare such version "numbers" (which are really just plain
+strings) using any of the usual string comparison operators C<eq>, C<ne>,
+C<lt>, C<gt>, etc., or perform bitwise string operations on them using C<|>,
+C<&>, etc.
 
 In conjunction with the new C<$^V> magic variable (which contains
-the perl version in this format), such literals can be used to
-check if you're running a particular version of Perl.
+the perl version as a string), such literals can be used as a readable way
+to check if you're running a particular version of Perl:
 
+    # this will parse in older versions of Perl also
     if ($^V and $^V gt v5.5.640) {
-        # new style version numbers are supported
+        # new features supported
     }
 
-C<require> and C<use> also support such literals:
+C<require> and C<use> also have some special magic to support such literals.
+They will be interpreted as a version rather than as a module name:
 
     require v5.6.0;		# croak if $^V lt v5.6.0
     use v5.6.0;			# same, but croaks at compile-time
 
-C<sprintf> and C<printf> support the Perl-specific format flag C<%v>
+Also, C<sprintf> and C<printf> support the Perl-specific format flag C<%v>
 to print ordinals of characters in arbitrary strings:
 
     printf "v%vd", $^V;		# prints current version, such as "v5.5.650"
     printf "%*vX", ":", $addr;	# formats IPv6 address
     printf "%*vb", "", $bits;	# displays bitstring as contiguous 0's and 1's
 
+See L<perlop/"Strings of Character"> for additional information.
+
 =head2 Weak references
 
 WARNING: This is an experimental feature.
@@ -852,9 +860,12 @@ only during normal running are warranted.  See L<perlvar>.
 
 =head2 New variable $^V contains Perl version in v5.6.0 format
 
-C<$^V> contains the Perl version number as a version tuple that
-can be used in string or numeric comparisons.  See
-C<Support for version tuples> for an example.
+C<$^V> contains the Perl version number as a string comprised of
+characters whose ordinals match the version numbers, so that it may
+be used in string comparisons.
+
+See C<Support for strings represented as a vector of ordinals> for an
+example.
 
 =head2 Optional Y2K warnings
 
@@ -1389,6 +1400,11 @@ For other details, see L<Benchmark>.
 The Devel::Peek module provides access to the internal representation
 of Perl variables and data.  It is a data debugging tool for the XS programmer.
 
+=item English
+
+$PERL_VERSION now stands for C<$^V> (a string value) rather than for C<$]>
+(a numeric value).
+
 =item ExtUtils::MakeMaker
 
 change#4135, also needs docs in module pod
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index ae1f44298d..f4cee09073 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -3549,9 +3549,17 @@ rename(2) manpage or equivalent system documentation for details.
 =item require
 
 Demands some semantics specified by EXPR, or by C<$_> if EXPR is not
-supplied.  If a version number or tuple is specified, or if EXPR is
-numeric, demands that the current version of Perl
-(C<$^V> or C<$]> or $PERL_VERSION) be equal or greater than EXPR.
+supplied.
+
+If a VERSION is specified as a literal of the form v5.6.0,
+demands that the current version of Perl (C<$^V> or $PERL_VERSION) be
+at least as recent as that version, at run time.  (For compatibility
+with older versions of Perl, a numeric argument will also be interpreted
+as VERSION.)  Compare with L</use>, which can do a similar check at
+compile time.
+
+    require v5.6.0;	# run time version check
+    require 5.005_03;	# same, number still supported for compatibility
 
 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
@@ -5247,13 +5255,17 @@ package.  It is exactly equivalent to
 
 except that Module I<must> be a bareword.
 
-If the first argument to C<use> is a number or a version tuple, it is
-treated as a version instead of a module name.  If the version
-of the Perl interpreter is less than VERSION, then an error message
-is printed and Perl exits immediately.
+VERSION, which can be specified as a literal of the form v5.6.0, demands
+that the current version of Perl (C<$^V> or $PERL_VERSION) be at least
+as recent as that version.  (For compatibility with older versions of Perl,
+a numeric literal will also be interpreted as VERSION.)  If the version
+of the running Perl interpreter is less than VERSION, then an error
+message is printed and Perl exits immediately without attempting to
+parse the rest of the file.  Compare with L</require>, which can do a
+similar check at run time.
 
-    use 5.005_03;	# version number
-    use v5.6.0;		# version tuple
+    use v5.6.0;		# compile time version check
+    use 5.005_03;	# same, number still supported for compatibility
 
 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
@@ -5280,7 +5292,7 @@ That is exactly equivalent to
 If the VERSION argument is present between Module and LIST, then the
 C<use> will call the VERSION method in class Module with the given
 version as an argument.  The default VERSION method, inherited from
-the Universal class, croaks if the given version is larger than the
+the UNIVERSAL class, croaks if the given version is larger than the
 value of the variable C<$Module::VERSION>. 
 
 Again, there is a distinction between omitting LIST (C<import> called
diff --git a/pod/perlop.pod b/pod/perlop.pod
index d932704666..15124125a3 100644
--- a/pod/perlop.pod
+++ b/pod/perlop.pod
@@ -1802,17 +1802,18 @@ operation you intend by using C<""> or C<0+>, as in the examples below.
 See L<perlfunc/vec> for information on how to manipulate individual bits
 in a bit vector.
 
-=head2 Version tuples
-
-A literal of the form C<v1.20.300.4000> is parsed as a dual-valued quantity.
-It has the string value of C<"\x{1}\x{14}\x{12c}\x{fa0}"> (i.e., a UTF-8
-string) and a numeric value of C<1 + 20/1000 + 300/1000000 + 4000/1000000000>.
-This is useful for representing Unicode strings, and for comparing version
-numbers using the string comparison operators, C<cmp>, C<gt>, C<lt> etc.
-
-Such "version tuples" or "vectors" are accepted by both C<require> and
-C<use>.  The C<$^V> variable contains the running Perl interpreter's
-version in this format.  See L<perlvar/$^V>.
+=head2 Strings of Character
+
+A literal of the form C<v1.20.300.4000> is parsed as a string comprised
+of characters with the specified ordinals.  This provides an alternative,
+more readable way to construct strings, rather than use the somewhat less
+readable interpolation form C<"\x{1}\x{14}\x{12c}\x{fa0}">.  This is useful
+for representing Unicode strings, and for comparing version "numbers"
+using the string comparison operators, C<cmp>, C<gt>, C<lt> etc.
+
+Such literals are accepted by both C<require> and C<use> for doing a version
+check.  The C<$^V> special variable also contains the running Perl
+interpreter's version in this form.  See L<perlvar/$^V>.
 
 =head2 Integer Arithmetic
 
diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index 285a0d5863..947942c003 100644
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -699,8 +699,6 @@ As of release 5 of Perl, assignment to C<$[> is treated as a compiler
 directive, and cannot influence the behavior of any other file.
 Its use is highly discouraged.
 
-=item $PERL_VERSION
-
 =item $]
 
 The version + patchlevel / 1000 of the Perl interpreter.  This variable
@@ -713,7 +711,10 @@ 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.
 
-See C<$^V> for a more modern representation of the Perl version.
+The use of this variable is deprecated.  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
 
@@ -905,24 +906,23 @@ The time at which the program began running, in seconds since the
 epoch (beginning of 1970).  The values returned by the B<-M>, B<-A>,
 and B<-C> filetests are based on this value.
 
-=item $PERL_VERSION_TUPLE
+=item $PERL_VERSION
 
 =item $^V
 
 The revision, version, and subversion of the Perl interpreter, represented
-as a "version tuple".  Version tuples have both a numeric value and a
-string value.  The numeric value is a floating point number that amounts
-to revision + version/1000 + subversion/1000000, and the string value
-is made of characters possibly in the UTF-8 range:
-C<chr($revision) . chr($version) . chr($subversion)>.
+as a string comprised 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
+C<$^V eq v5.6.0>.  Note that the characters in this string value can
+potentially be in Unicode range.
 
 This can be used to determine whether the Perl interpreter executing a
 script is in the right range of versions.  (Mnemonic: use ^V for Version
-control.)  Example:
+Control.)  Example:
 
-    warn "No "our" declarations!\n" if $^V and $^V lt v5.6;
+    warn "No "our" declarations!\n" if $^V and $^V lt v5.6.0;
 
-See also the documentation of C<use VERSION> and C<require VERSION>
+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.