Integrate from mainperl.

p4raw-id: //depot/cfgperl@3047

5 files changed, 84 insertions, 8 deletions

diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index d841d28b87..329b1d0a08 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -161,6 +161,28 @@ strings.  See L<perlfunc/"pack">.
 The new format type modifer '_' is useful for packing and unpacking
 native shorts, ints, and longs.  See L<perlfunc/"pack">.
 
+=head2 $^X variables may now have names longer than one character
+
+Formerly, $^X was synonymous with ${"\cX"}, but $^XY was a syntax
+error.  Now variable names that begin with a control character may be
+arbitrarily long.  However, for compatibility reasons, these variables
+I<must> be written with explicit braces, as C<${^XY}> for example.
+C<${^XYZ}> is synonymous with ${"\cXYZ"}. Variable names with more
+than one control character, such as C<${^XY^Z}>, are illegal.
+
+The old syntax has not changed.  As before, the `^X' may either be a
+literal control-X character or the two character sequence `caret' plus
+`X'.  When the braces are omitted, the variable name stops after the
+control character.  Thus C<"$^XYZ"> continues to be synonymous with
+C<$^X . "YZ"> as before.  
+
+As before, lexical variables may not have names beginning with control
+characters.  As before, variables whose names begin with a control
+character are always forced to be in package `main'.  These variables
+are all reserved for future extensions, except the ones that begin
+with C<^_>, which may be used by user programs and will not acquire a
+special meaning in any future version of Perl.
+
 =head1 Significant bug fixes
 
 =head2 E<lt>HANDLEE<gt> on empty files
diff --git a/pod/perlhist.pod b/pod/perlhist.pod
index 40aa83c1f2..b5bda55177 100644
--- a/pod/perlhist.pod
+++ b/pod/perlhist.pod
@@ -316,6 +316,7 @@ the strings?).
           5.005_53      1998-Oct-31
           5.005_54      1998-Nov-30
           5.005_55      1999-Feb-16
+          5.005_56      1999-Mar-01
 
 =head2 SELECTED RELEASE SIZES
 
diff --git a/pod/perltodo.pod b/pod/perltodo.pod
index fe339dec79..4b5a5063e3 100644
--- a/pod/perltodo.pod
+++ b/pod/perltodo.pod
@@ -117,11 +117,6 @@ Verify complete 64 bit support so that the value of sysseek, or C<-s>, or
 stat(), or tell can fit into a perl number without losing precision.
 Work with the perl-64bit mailing list on perl.org.
 
-=head2 Figure a way out of $^(capital letter)
-
-Figure out a clean way to extend $^(capital letter) beyond
-the 26 alphabets.  (${^WORD} maybe?)
-
 =head2 Prototypes
 
 =over 4
@@ -237,6 +232,7 @@ will be difficult.
     CPP-space:    restrict CPP symbols exported from headers
     header-space: move into CORE/perl/
     API-space:    begin list of things that constitute public api
+    env-space:    Configure should use PERL_CONFIG instead of CONFIG etc.
 
 =head2 MULTIPLICITY
 
@@ -378,7 +374,9 @@ Make C<perldoc> tell users what they need to add to their .login or
 =head2 Install ALL Documentation
 
 Make the standard documentation kit include the VMS, OS/2, Win32,
-Threads, etc information.
+Threads, etc information.  installperl and pod/Makefile should know
+enough to copy README.foo to perlfoo.pod before building everything,
+when appropriate.
 
 =head2 Outstanding issues to be documented
 
@@ -839,6 +837,13 @@ Can we install modules as bytecode?
 
 =head1 Recently Finished Tasks
 
+=head2 Figure a way out of $^(capital letter)
+
+Figure out a clean way to extend $^(capital letter) beyond
+the 26 alphabets.  (${^WORD} maybe?)
+
+Mark-Jason Dominus sent a patch which went into 5.005_56.
+
 =head2 Filenames
 
 Make filenames in the distribution and in the standard module set
diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index 2dafc1ca1a..5c851d9c15 100644
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -1005,3 +1005,51 @@ pipe C<close>, overwriting the old value.
 
 For more details, see the individual descriptions at L<$@>, L<$!>, L<$^E>,
 and L<$?>.
+
+
+=head2 Technical Note on the Syntax of Variable Names
+
+Variable names in Perl can have several formats.  Usually, they must
+begin with a letter or underscore, in which case they can be
+arbitrarily long (up to an internal limit of 256 characters) and may
+contain letters, digits, underscores, or the special sequence C<::>.
+In this case the part before the last C<::> is taken to be a I<package
+qualifier>; see L<perlmod>. 
+
+Perl variable names may also be a sequence of digits or a single
+punctuation or control character.  These names are all reserved for
+special uses by Perl; for example, the all-digits names are used to
+hold backreferences after a regulare expression match.  Perl has a
+special syntax for the single-control-character names: It understands
+C<^X> (caret C<X>) to mean the control-C<X> character.  For example,
+the notation C<$^W> (dollar-sign caret C<W>) is the scalar variable
+whose name is the single character control-C<W>.  This is better than
+typing a literal control-C<W> into your program.
+
+Finally, new in Perl 5.006, Perl variable names may be alphanumeric
+strings that begin with control characters.  These variables must be
+written in the form C<${^Foo}>; the braces are not optional.
+C<${^Foo}> denotes the scalar variable whose name is a control-C<F>
+followed by two C<o>'s.  These variables are reserved for future
+special uses by Perl, except for the ones that begin with C<^_>
+(control-underscore).  No control-character name that begins with
+C<^_> will acquire a special meaning in any future version of Perl;
+such names may therefore be used safely in programs.  C<^_> itself,
+however, I<is> reserved.
+
+All Perl variables that begin with digits, control characters, or
+punctuation characters are exempt from the effects of the C<package>
+declaration and are always forced to be in package C<main>.  A few
+other names are also exempt:
+
+	ENV		STDIN
+	INC		STDOUT
+	ARGV		STDERR
+	ARGVOUT
+	SIG
+
+In particular, the new special C<${^_XYZ}> variables are always taken
+to be in package C<main> regardless of any C<package> declarations
+presently in scope.
+
+
diff --git a/pod/pod2man.PL b/pod/pod2man.PL
index 3c55d6e29c..11bb74bd67 100644
--- a/pod/pod2man.PL
+++ b/pod/pod2man.PL
@@ -678,8 +678,8 @@ $indent = 0;
 
 $begun = "";
 
-# Unrolling [^A-Z>]|[A-Z](?!<) gives:    // MRE pp 165.
-my $nonest = '(?:[^A-Z>]*(?:[A-Z](?!<)[^A-Z>]*)*)';
+# Unrolling [^-=A-Z>]|[A-Z](?!<)|[-=][\x00-\xFF] gives:    // MRE pp 165.
+my $nonest = '(?:[^-=A-Z>]*(?:(?:[-=][\x00-\xFF]|[A-Z](?!<))[^-=A-Z>]*)*)';
 
 while (<>) {
     if ($cutting) {