Resync with mainline

p4raw-id: //depot/vmsperl@5049
p4raw-branched: from //depot/perl@4822 'branch in'
	ext/Sys/Syslog/Makefile.PL ext/Sys/Syslog/Syslog.pm
	lib/Pod/Find.pm lib/Pod/ParseUtils.pm t/op/exists_sub.t
	t/op/ver.t t/pragma/diagnostics.t win32/bin/exetype.pl
	vos/config.def vos/config.pl (@4896..) pod/perlintern.pod
	(@4915..) ext/Sys/Syslog/Syslog.xs (@4980..)
	pod/perlunicode.pod (@5013..) pod/perlapi.pod (@5015..)
	Todo-5.6 (@5027..)
p4raw-deleted: from //depot/perl@4822 'delete in' lib/Sys/Syslog.pm
	(@2406..) Todo-5.005 (@4008..) lib/caller.pm (@4860..)
p4raw-edited: from //depot/perl@4822 'edit in' vms/subconfigure.com
	(@4767..)
p4raw-integrated: from //depot/perl@4822 'copy in' hints/unicosmk.sh
	(@948..) lib/FileHandle.pm (@1044..) lib/ExtUtils/Packlist.pm
	(@1315..) ext/IPC/SysV/SysV.pm (@1372..) lib/Net/protoent.pm
	lib/Net/servent.pm lib/Text/Soundex.pm (@1575..) README.vos
	vos/Changes vos/build.cm vos/compile_perl.cm vos/perl.bind
	vos/test_vos_dummies.c vos/vos_dummies.c (@1838..)
	lib/utf8_heavy.pl (@2039..) ext/IO/lib/IO/Seekable.pm
	lib/ExtUtils/Command.pm lib/Net/hostent.pm lib/Net/netent.pm
	lib/Time/gmtime.pm lib/Time/localtime.pm lib/User/grent.pm
	lib/User/pwent.pm (@2620..) eg/cgi/index.html lib/CGI/Apache.pm
	lib/CGI/Switch.pm (@2830..) ext/IO/lib/IO/Dir.pm
	ext/IO/lib/IO/Pipe.pm ext/IO/lib/IO/Poll.pm
	ext/IO/lib/IO/Socket/UNIX.pm (@2882..) t/comp/use.t (@2891..)
	lib/File/Compare.pm (@3061..) form.h (@3124..) hints/netbsd.sh
	(@3158..) t/op/grep.t (@3180..) lib/AnyDBM_File.pm (@3317..)
	lib/Test.pm (@3376..) lib/CPAN/Nox.pm (@3458..)
	hints/openbsd.sh (@3516..) mg.h (@3524..) lib/CGI/Cookie.pm
	lib/CGI/Pretty.pm (@3559..) lib/Text/ParseWords.pm (@3563..)
	ext/IO/lib/IO/File.pm lib/File/Basename.pm (@3650..)
	x2p/find2perl.PL (@3677..) cflags.SH (@3774..) utils/dprofpp.PL
	(@3778..) ext/IO/lib/IO/Handle.pm (@3825..) lib/CGI.pm
	lib/dumpvar.pl (@3848..) README.cygwin
	lib/ExtUtils/MM_Cygwin.pm (@3852..) README.threads (@3860..)
	lib/SelfLoader.pm t/io/tell.t t/lib/cgi-html.t t/op/attrs.t
	(@4076..) ext/SDBM_File/sdbm/sdbm.c (@4082..)
	lib/Test/Harness.pm (@4092..) pod/perlcompile.pod (@4120..)
	ext/Opcode/Safe.pm (@4131..) ext/DB_File/Changes
	ext/DB_File/Makefile.PL ext/DB_File/version.c (@4142..)
	ext/DB_File/DB_File.xs (@4144..) lib/File/Spec/VMS.pm (@4182..)
	hints/dynixptx.sh (@4271..) t/lib/fields.t (@4303..) thrdvar.h
	(@4316..) pod/perlguts.pod (@4339..) Porting/makerel (@4391..)
	lib/Text/Tabs.pm (@4398..) perlio.c (@4402..)
	lib/CPAN/FirstTime.pm (@4416..) README (@4433..)
	lib/attributes.pm (@4438..) ext/Devel/Peek/Peek.xs (@4475..)
	Policy_sh.SH (@4496..) universal.c xsutils.c (@4511..)
	ext/B/B/Stash.pm ext/B/NOTES ext/B/O.pm keywords.h keywords.pl
	(@4515..) util.h (@4545..) ext/B/B/Asmdata.pm
	ext/B/B/Deparse.pm (@4546..) ext/Data/Dumper/Dumper.xs
	pod/perlmod.pod (@4556..) ext/IO/IO.xs lib/unicode/Is/ASCII.pl
	lib/unicode/Is/Alnum.pl lib/unicode/Is/Alpha.pl
	lib/unicode/Is/BidiAN.pl lib/unicode/Is/BidiB.pl
	lib/unicode/Is/BidiCS.pl lib/unicode/Is/BidiEN.pl
	lib/unicode/Is/BidiES.pl lib/unicode/Is/BidiET.pl
	lib/unicode/Is/BidiL.pl lib/unicode/Is/BidiON.pl
	lib/unicode/Is/BidiR.pl lib/unicode/Is/BidiS.pl
	lib/unicode/Is/BidiWS.pl lib/unicode/Is/C.pl
	lib/unicode/Is/Cc.pl lib/unicode/Is/Cn.pl
	lib/unicode/Is/Cntrl.pl lib/unicode/Is/Co.pl
	lib/unicode/Is/DCcircle.pl lib/unicode/Is/DCcompat.pl
	lib/unicode/Is/DCfinal.pl lib/unicode/Is/DCfont.pl
	lib/unicode/Is/DCinital.pl lib/unicode/Is/DCinitial.pl
	lib/unicode/Is/DCisolated.pl lib/unicode/Is/DCnarrow.pl
	lib/unicode/Is/DCnoBreak.pl lib/unicode/Is/DCsmall.pl
	lib/unicode/Is/DCsquare.pl lib/unicode/Is/DCsub.pl
	lib/unicode/Is/DCsuper.pl lib/unicode/Is/DCvertical.pl
	lib/unicode/Is/DCwide.pl lib/unicode/Is/DecoCanon.pl
	lib/unicode/Is/DecoCompat.pl lib/unicode/Is/Digit.pl
	lib/unicode/Is/Graph.pl lib/unicode/Is/L.pl
	lib/unicode/Is/Ll.pl lib/unicode/Is/Lm.pl lib/unicode/Is/Lo.pl
	lib/unicode/Is/Lower.pl lib/unicode/Is/Lt.pl
	lib/unicode/Is/Lu.pl lib/unicode/Is/M.pl lib/unicode/Is/Mc.pl
	lib/unicode/Is/Mirrored.pl lib/unicode/Is/Mn.pl
	lib/unicode/Is/N.pl lib/unicode/Is/Nd.pl lib/unicode/Is/No.pl
	lib/unicode/Is/P.pl lib/unicode/Is/Pd.pl lib/unicode/Is/Pe.pl
	lib/unicode/Is/Po.pl lib/unicode/Is/Print.pl
	lib/unicode/Is/Ps.pl lib/unicode/Is/Punct.pl
	lib/unicode/Is/S.pl lib/unicode/Is/Sc.pl lib/unicode/Is/Sm.pl
	lib/unicode/Is/So.pl lib/unicode/Is/Space.pl (@4573..) perly.c
	vms/perly_c.vms (@4578..) deb.c (@4588..) lib/Pod/Checker.pm
	lib/Pod/Parser.pm lib/Pod/Usage.pm t/pod/poderrs.t
	t/pod/poderrs.xr (@4590..) pod/Makefile pod/roffitall unixish.h
	vos/vosish.h (@4602..) run.c (@4603..) utils/perlbug.PL
	utils/perldoc.PL (@4604..) hints/hpux.sh (@4606..)
	lib/strict.pm pod/perlsyn.pod (@4616..) ext/DB_File/DB_File.pm
	ext/Fcntl/Fcntl.pm ext/GDBM_File/GDBM_File.pm
	ext/Opcode/Opcode.pm ext/SDBM_File/SDBM_File.pm
	ext/Socket/Socket.pm lib/AutoLoader.pm lib/Getopt/Std.pm
	(@4623..) lib/ExtUtils/Manifest.pm (@4632..) pod/perlfaq2.pod
	(@4636..) t/op/misc.t t/pragma/warn/2use (@4641..)
	lib/Math/BigFloat.pm (@4685..) pod/perlfilter.pod
	pod/perlopentut.pod (@4699..) t/pragma/warn/pp_hot
	t/pragma/warn/pp_sys (@4709..) cygwin/Makefile.SHs
	os2/Makefile.SHs (@4710..) lib/Net/Ping.pm (@4711..)
	ext/POSIX/POSIX.xs ext/SDBM_File/sdbm/pair.c (@4717..)
	lib/ExtUtils/Liblist.pm (@4720..) t/lib/charnames.t
	t/lib/dumper.t (@4723..) lib/byte_heavy.pl (@4726..)
	t/pragma/warn/doop t/pragma/warn/pp t/pragma/warn/sv
	t/pragma/warn/utf8 (@4727..) lib/ExtUtils/xsubpp (@4731..)
	pod/perlre.pod (@4732..) INTERN.h (@4734..) globals.c (@4744..)
	lib/File/Copy.pm (@4753..) lib/ExtUtils/MM_VMS.pm
	lib/ExtUtils/MM_Win32.pm (@4754..) lib/ExtUtils/Install.pm
	(@4758..) ext/B/B/C.pm (@4763..) README.os2 (@4766..)
	lib/ExtUtils/MakeMaker.pm (@4769..) installperl (@4774..)
	lib/CPAN.pm lib/ExtUtils/Installed.pm lib/ExtUtils/MM_Unix.pm
	lib/ExtUtils/Mksymlists.pm lib/diagnostics.pm (@4777..)
	t/lib/thread.t (@4780..) pod/perl.pod (@4781..)
	ext/IO/lib/IO/Socket.pm (@4782..) win32/perlhost.h (@4792..)
	lib/Tie/Array.pm (@4796..) t/pragma/strict-vars (@4801..)
	win32/config.bc win32/config.gc win32/config.vc (@4817..)
	INSTALL (@4824..) utils/h2xs.PL (@4825..) embed.h (@4830..)
	ext/Data/Dumper/Dumper.pm (@4832..) lib/Tie/Handle.pm (@4833..)
	proto.h t/op/closure.t (@4834..) lib/base.pm lib/fields.pm
	(@4835..) dump.c (@4836..) t/io/fs.t (@4838..)
	lib/Carp/Heavy.pm (@4839..) t/cmd/while.t (@4848..)
	Porting/Glossary Porting/config.sh Porting/config_H (@4850..)
	lib/Sys/Hostname.pm (@4851..) ext/Devel/DProf/DProf.pm
	(@4852..) hints/cygwin.sh (@4853..) patchlevel.h (@4858..)
	ext/File/Glob/Glob.pm ext/IO/lib/IO/Socket/INET.pm
	ext/NDBM_File/NDBM_File.pm ext/ODBM_File/ODBM_File.pm
	ext/POSIX/POSIX.pm lib/Dumpvalue.pm lib/Fatal.pm
	lib/File/Path.pm lib/File/stat.pm lib/Math/Complex.pm
	lib/Math/Trig.pm lib/Shell.pm lib/constant.pm lib/lib.pm
	(@4860..) lib/AutoSplit.pm (@4873..) lib/Pod/Html.pm (@4883..)
	win32/perllib.c (@4884..) vos/config.h vos/config_h.SH_orig
	(@4896..) perly.y pod/perlrun.pod pod/perlsub.pod
	pod/perltodo.pod (@4905..) README.win32 lib/Class/Struct.pm
	(@4906..) Porting/p4desc (@4908..) ext/Devel/Peek/Peek.pm
	ext/Thread/Thread.pm lib/File/Find.pm lib/UNIVERSAL.pm
	pod/buildtoc pod/perlfork.pod (@4910..) t/op/fork.t (@4914..)
	XSUB.h av.h cop.h cv.h gv.h handy.h hv.h makedef.pl
	pod/perltoc.pod pp.h scope.h (@4915..) global.sym objXSUB.h
	(@4916..) lib/Cwd.pm (@4921..) doop.c t/pragma/warn/toke
	(@4930..) win32/win32.c (@4933..) embedvar.h intrpvar.h
	lib/charnames.pm op.h sv.h (@4937..) embed.pl (@4939..)
	lib/utf8.pm regcomp.c regexec.c (@4941..)
	vms/descrip_mms.template (@4944..) lib/warnings.pm warnings.pl
	(@4947..) lib/File/Spec/Win32.pm (@4949..) lib/perl5db.pl
	(@4955..) lib/Benchmark.pm (@4958..) lib/English.pm (@4960..)
	lib/byte.pm (@4969..) scope.c (@4970..)
	ext/Devel/DProf/DProf.xs (@4973..) malloc.c (@4974..) op.c
	pod/perldebug.pod pp_ctl.c (@4975..) Makefile.SH (@4977..)
	config_h.SH (@4978..) pod/perlop.pod (@4979..) pod/perlfunc.pod
	(@4998..) pod/perldiag.pod (@5001..) pp_sys.c (@5006..)
	EXTERN.h doio.c perl.h util.c (@5008..) av.c hv.c pp.c pp_hot.c
	utf8.c utf8.h (@5009..) pod/perldelta.pod pod/perlport.pod
	(@5015..) MANIFEST (@5016..) sv.c (@5017..) win32/config_H.bc
	win32/config_H.gc win32/config_H.vc (@5019..) win32/Makefile
	win32/makefile.mk (@5022..) win32/win32.h (@5024..) mg.c toke.c
	(@5025..) gv.c perl.c pod/perlvar.pod (@5029..)
	pod/perlhist.pod (@5034..) Configure (@5036..) Changes
	(@5038..) 'merge in' configure.com (@4773..)

1 files changed, 56 insertions, 44 deletions

diff --git a/INSTALL b/INSTALL
index 7ac14caef2..d38778305c 100644
--- a/INSTALL
+++ b/INSTALL
@@ -8,7 +8,8 @@ First, make sure you are installing an up-to-date version of Perl.   If
 you didn't get your Perl source from CPAN, check the latest version at
 <URL:http://www.perl.com/CPAN/src/>.
 
-The basic steps to build and install perl5 on a Unix system are:
+The basic steps to build and install perl5 on a Unix system
+with all the defaults are:
 
 	rm -f config.sh Policy.sh
 	sh Configure -de
@@ -42,20 +43,6 @@ For information on what's new in this release, see the
 pod/perldelta.pod file.  For more detailed information about specific
 changes, see the Changes file.
 
-IMPORTANT NOTE:  5.005_53 and later releases do not export unadorned
-global symbols anymore.  This means you may need to build older
-extensions that have not been updated for the new naming convention
-with:
-
-	perl Makefile.PL POLLUTE=1
-	
-Alternatively, you can enable CPP symbol pollution wholesale by
-building perl itself with:
-
-	sh Configure -Accflags=-DPERL_POLLUTE
-
-pod/perldelta.pod contains more details about this.
-
 =head1 DESCRIPTION
 
 This document is written in pod format as an easy way to indicate its
@@ -67,7 +54,8 @@ by lines beginning with '='.  The other mark-up used is
     C<code>	literal code
     L<name>     A link (cross reference) to name
 
-You should probably at least skim through this entire document before
+Although most of the defaults are probably fine for most users,
+you should probably at least skim through this entire document before
 proceeding.
 
 If you're building Perl on a non-Unix system, you should also read
@@ -80,6 +68,22 @@ system.  (Unixware users should use the svr4.sh hint file.)  If
 there is a README file for your platform, then you should read
 that too.  Additional information is in the Porting/ directory.
 
+=head1 WARNING:  This version requires an extra step to build old extensions.
+
+5.005_53 and later releases do not export unadorned
+global symbols anymore.  This means you may need to build older
+extensions that have not been updated for the new naming convention
+with:
+
+	perl Makefile.PL POLLUTE=1
+	
+Alternatively, you can enable CPP symbol pollution wholesale by
+building perl itself with:
+
+	sh Configure -Accflags=-DPERL_POLLUTE
+
+pod/perldelta.pod contains more details about this.
+
 =head1 WARNING:  This version may not be binary compatible with Perl 5.005.
 
 Using the default Configure options for building perl should get you
@@ -102,7 +106,7 @@ The standard extensions supplied with Perl will be handled automatically.
 On a related issue, old modules may possibly be affected by the
 changes in the Perl language in the current release.  Please see
 pod/perldelta.pod (and pod/perl500Xdelta.pod) for a description of
-what's changed.  See also your installed copy of the perllocal.pod
+what's changed.  See your installed copy of the perllocal.pod
 file for a (possibly incomplete) list of locally installed modules.
 Also see CPAN::autobundle for one way to make a "bundle" of your
 currently installed modules.
@@ -126,10 +130,10 @@ followed.  This will enable us to officially support this option.
 
 =head1 Space Requirements
 
-The complete perl5 source tree takes up about 15 MB of disk space.
-After completing make, it takes up roughly 20 MB, though the actual
+The complete perl5 source tree takes up about 20 MB of disk space.
+After completing make, it takes up roughly 30 MB, though the actual
 total is likely to be quite system-dependent.  The installation
-directories need something on the order of 15 MB, though again that
+directories need something on the order of 20 MB, though again that
 value is system-dependent.
 
 =head1 Start with a Fresh Distribution
@@ -333,7 +337,7 @@ The directories set up by Configure fall into three broad categories.
 
 =item Directories for the perl distribution
 
-By default, Configure will use the following directories for 5.6.
+By default, Configure will use the following directories for 5.6.0.
 $version is the full perl version number, including subversion, e.g.
 5.6.0 or 5.6.1, and $archname is a string like sun4-sunos,
 determined by Configure.  The full definitions of all Configure
@@ -360,8 +364,7 @@ the common style is shown here.
 
 After perl is installed, you may later wish to add modules (e.g. from
 CPAN) or scripts.  Configure will set up the following directories to
-be used for installing those add-on modules and scripts.  $version
-is the perl version number, e.g. 5.6.0.
+be used for installing those add-on modules and scripts.
 
     Configure variable	Default value
     $siteprefix		$prefix
@@ -582,7 +585,7 @@ If the generated Policy.sh file is unsuitable, you may freely edit it
 to contain any valid shell commands.  It will be run just after the
 platform-specific hints files.
 
-Note:  Since the directory hierarchy for 5.6 contains a number of
+Note:  Since the directory hierarchy for 5.6.0 contains a number of
 new vendor* and site* entries, your Policy.sh file will probably not
 set them to your desired values.  I encourage you to run Configure
 interactively to be sure it puts things where you want them.
@@ -881,7 +884,17 @@ the Configure command line.  Similarly, the Opcode extension is always
 built by default, but you can skip it by setting the Configure variable
 useopcode=false either in a hint file for from the command line.
 
-You can learn more about each of these extensions by consulting the
+If you unpack any additional extensions in the ext/ directory before
+running Configure, then Configure will offer to build those additional
+extensions as well.  Most users probably shouldn't have to do this --
+it is usually easier to build additional extensions later after perl
+has been installed.  However, if you wish to have those additional
+extensions statically linked into the perl binary, then this offers a
+convenient way to do that in one step.  (It is not necessary, however;
+you can build and install extensions just fine even if you don't have
+dynamic loading.  See lib/ExtUtils/MakeMaker.pm for more details.)
+
+You can learn more about each of the supplied extensions by consulting the
 documentation in the individual .pm modules, located under the
 ext/ subdirectory.
 
@@ -904,7 +917,7 @@ to turn off each extension:
     SDBM_File		(Always included by default)
     Opcode		useopcode
     Socket		d_socket
-    Threads		usethreads
+    Threads		use5005threads
     attrs		(Always included by default)
 
 Thus to skip the NDBM_File extension, you can use
@@ -1133,8 +1146,9 @@ $ccflags or $optimize, and then re-run
 
 =item No sh
 
-If you don't have sh, you'll have to copy the sample file Porting/config_H
-to config.h and edit the config.h to reflect your system's peculiarities.
+If you don't have sh, you'll have to copy the sample file
+Porting/config.sh to config.sh and edit your config.sh to reflect your
+system's peculiarities.  See Porting/pumpkin.pod for more information.
 You'll probably also have to extensively modify the extension building
 mechanism.
 
@@ -1179,7 +1193,7 @@ libgdbm under HP-UX 11.
 Specific information for the OS/2, Plan9, VMS and Win32 ports is in the
 corresponding README files and subdirectories.  Additional information,
 including a glossary of all those config.sh variables, is in the Porting
-subdirectory.  Especially Porting/Glossary should come in handy. 
+subdirectory.  Especially Porting/Glossary should come in handy.
 
 Ports for other systems may also be available.  You should check out
 http://www.perl.com/CPAN/ports for current information on ports to
@@ -1704,8 +1718,9 @@ searched by version 5.6.0 will be
 
 	/usr/local/lib/perl5/site_perl/5.005/$archname
 	/usr/local/lib/perl5/site_perl/5.005
+	/usr/local/lib/perl5/site_perl/
 
-Notice the last two entries -- Perl understands the default structure
+Notice the last three entries -- Perl understands the default structure
 of the $sitelib directories and will look back in older, compatible
 directories.  This way, modules installed under 5.005_03 will continue
 to be usable by 5.005_03 but will also accessible to 5.6.0.  Further,
@@ -1714,11 +1729,8 @@ present only in 5.6.0.  That new module will get installed into
 /usr/local/lib/perl5/site_perl/5.6.0 and will be available to 5.6.0,
 but will not interfere with the 5.005_03 version.
 
-Also, by default, 5.6.0 will look in
-
-	/usr/local/lib/perl5/site_perl/
-
-for 5.004-era pure perl modules.
+The last entry, /usr/local/lib/perl5/site_perl/, is there so that
+5.6.0 will look for 5.004-era pure perl modules.
 
 Lastly, suppose you now install version 5.6.1, which we'll assume is
 binary compatible with 5.6.0 and 5.005.  The directories searched
@@ -1775,15 +1787,15 @@ yet.
 
 =head2 Upgrading from 5.005 to 5.6.0
 
-Extensions built and installed with versions of perl prior to 5.005_50
-will need to be recompiled to be used with 5.005_50 and later.  You will,
-however, be able to continue using 5.005 even after you install 5.6.
-The 5.005 binary will still be able to find the modules built under
-5.005; the 5.6.0 binary will look in the new $sitearch and $sitelib
-directories, and will not find them.  See also your installed copy
-of the perllocal.pod file for a (possibly incomplete) list of locally
-installed modules.  Note that you want perllocal.pod not perllocale.pod
-for installed module information.
+Most extensions built and installed with versions of perl
+prior to 5.005_50 will not need to be recompiled to be used with
+5.6.0.  If you find you do need to rebuild an extension with 5.6.0,
+you may safely do so without disturbing the 5.005 installation.
+(See L<"Coexistence with earlier versions of perl5"> above.)
+
+See your installed copy of the perllocal.pod file for a (possibly
+incomplete) list of locally installed modules.  Note that you want
+perllocal.pod not perllocale.pod for installed module information.
 
 =head1 Coexistence with perl4