Some updates for perlvms.pod.

Remove some woefully out-of-date and/or incorrect material and fix
a few other nits.

1 files changed, 24 insertions, 60 deletions

diff --git a/pod/perlvms.pod b/pod/perlvms.pod
index 0362c3b9de..a6045be973 100644
--- a/pod/perlvms.pod
+++ b/pod/perlvms.pod
@@ -23,29 +23,27 @@ hesitate to drop a line to vmsperl@perl.org.
 
 Directions for building and installing Perl 5 can be found in 
 the file F<README.vms> in the main source directory of the 
-Perl distribution..
+Perl distribution.
 
 =head1 Organization of Perl Images
 
 =head2 Core Images
 
-During the installation process, three Perl images are produced.
+During the build process, three Perl images are produced.
 F<Miniperl.Exe> is an executable image which contains all of
 the basic functionality of Perl, but cannot take advantage of
-Perl extensions.  It is used to generate several files needed
-to build the complete Perl and various extensions.  Once you've
-finished installing Perl, you can delete this image.
-
-Most of the complete Perl resides in the shareable image
-F<PerlShr.Exe>, which provides a core to which the Perl executable
-image and all Perl extensions are linked.  You should place this
-image in F<Sys$Share>, or define the logical name F<PerlShr> to
-translate to the full file specification of this image.  It should
-be world readable.  (Remember that if a user has execute only access
-to F<PerlShr>, VMS will treat it as if it were a privileged shareable
-image, and will therefore require all downstream shareable images to be
-INSTALLed, etc.)
-
+Perl XS extensions and has a hard-wired list of library locations
+for loading pure-Perl modules.  It is used extensively to build and
+test Perl and various extensions, but is not installed.
+
+Most of the complete Perl resides in the shareable image F<PerlShr.Exe>,
+which provides a core to which the Perl executable image and all Perl
+extensions are linked. It is generally located via the logical name
+F<PERLSHR>.  While it's possible to put the image in F<SYS$SHARE> to
+make it loadable, that's not recommended. And while you may wish to
+INSTALL the image for performance reasons, you should not install it
+with privileges; if you do, the result will not be what you expect as
+image privileges are disabled during Perl start-up.
 
 Finally, F<Perl.Exe> is an executable image containing the main
 entry point for Perl, as well as some initialization code.  It
@@ -118,35 +116,10 @@ directory, and the procedure for building the extension is simply
     $ mmk test          ! Run test code, if supplied
     $ mmk install       ! Install into public Perl tree
 
-I<N.B.> The procedure by which extensions are built and
-tested creates several levels (at least 4) under the
-directory in which the extension's source files live.
-For this reason if you are running a version of VMS prior
-to V7.1 you shouldn't nest the source directory
-too deeply in your directory structure lest you exceed RMS'
-maximum of 8 levels of subdirectory in a filespec.  (You
-can use rooted logical names to get another 8 levels of
-nesting, if you can't place the files near the top of
-the physical directory structure.)
-
 VMS support for this process in the current release of Perl
-is sufficient to handle most extensions.  However, it does
-not yet recognize extra libraries required to build shareable
-images which are part of an extension, so these must be added
-to the linker options file for the extension by hand.  For
-instance, if the F<PGPLOT> extension to Perl requires the
-F<PGPLOTSHR.EXE> shareable image in order to properly link
-the Perl extension, then the line C<PGPLOTSHR/Share> must
-be added to the linker options file F<PGPLOT.Opt> produced
-during the build process for the Perl extension.
-
-By default, the shareable image for an extension is placed in
-the F<[.lib.site_perl.auto>I<Arch>.I<Extname>F<]> directory of the
-installed Perl directory tree (where I<Arch> is F<VMS_VAX> or
-F<VMS_AXP>, and I<Extname> is the name of the extension, with
-each C<::> translated to C<.>).  (See the MakeMaker documentation
-for more details on installation options for extensions.)
-However, it can be manually placed in any of several locations:
+is sufficient to handle most extensions.  (See the MakeMaker
+documentation for more details on installation options for
+extensions.)
 
 =over 4
 
@@ -214,12 +187,6 @@ the traditional VMS C<[...]>.  To be compatible with what MakeMaker
 expects, if a VMS path cannot be translated to a Unix path, it is
 passed through unchanged, so C<unixify("[...]")> will return C<[...]>.
 
-The handling of extended characters is largely complete in the
-VMS-specific C infrastructure of Perl, but more work is still needed to
-fully support extended syntax filenames in several core modules.  In
-particular, at this writing PathTools has only partial support for
-directories containing some extended characters.
-
 There are several ambiguous cases where a conversion routine cannot
 determine whether an input filename is in Unix format or in VMS format,
 since now both VMS and Unix file specifications may have characters in
@@ -248,15 +215,12 @@ not yet supported in Perl.
 
 =head2 Filename Case
 
-Perl follows VMS defaults and override settings in preserving (or not
-preserving) filename case.  Case is not preserved on ODS-2 formatted
-volumes on any architecture.  On ODS-5 volumes, filenames may be case
-preserved depending on process and feature settings.  Perl now honors
-DECC$EFS_CASE_PRESERVE and DECC$ARGV_PARSE_STYLE on those systems where
-the CRTL supports these features.  When these features are not enabled
-or the CRTL does not support them, Perl follows the traditional CRTL
-behavior of downcasing command-line arguments and returning file
-specifications in lower case only.
+Perl enables DECC$EFS_CASE_PRESERVE and DECC$ARGV_PARSE_STYLE by
+default.  Note that the latter only takes effect when extended parse
+is set in the process in which Perl is running.  When these features
+are explicitly disabled in the environment or the CRTL does not support
+them, Perl follows the traditional CRTL behavior of downcasing command-line
+arguments and returning file specifications in lower case only.
 
 I<N. B.>  It is very easy to get tripped up using a mixture of other
 programs, external utilities, and Perl scripts that are in varying
@@ -265,7 +229,7 @@ created by an older version of an archive utility or a build utility
 such as MMK or MMS may generate a filename in all upper case even on an
 ODS-5 volume.  If this filename is later retrieved by a Perl script or
 module in a case preserving environment, that upper case name may not
-match the mixed-case or lower-case exceptions of the Perl code.  Your
+match the mixed-case or lower-case expectations of the Perl code.  Your
 best bet is to follow an all-or-nothing approach to case preservation:
 either don't use it at all, or make sure your entire toolchain and
 application environment support and use it.