Updated, non-wordwrapped, patch to README.VMS

p4raw-id: //depot/perl@537

1 files changed, 7 insertions, 364 deletions

diff --git a/README.vms b/README.vms
index 4b8c29d345..40de6acac7 100644
--- a/README.vms
+++ b/README.vms
@@ -207,6 +207,13 @@ PERLDOC :== $PERL_ROOT:[000000]PERL PERL_ROOT:[LIB.POD]PERLDOC.COM -T
 7) Optionally define the command PERLBUG (the Perl bug report generator) as
 PERLBUG :== $PERL_ROOT:[000000]PERL PERL_ROOT:[LIB]PERLBUG.COM"
 
+8) Optionally define the command POD2MAN (Converts POD files to nroff
+source suitable for converting to man pages. Also quiets complaints during
+module builds) as
+
+DEFINE/NOLOG POD2MAN PERL_ROOT:[LIB.POD]POD2MAN.COM
+POD2MAN :== $PERL_ROOT:[000000]PERL POD2MAN
+
 * Installing Perl into DCLTABLES
 
 Courtesy of Brad  Hughes:
@@ -373,367 +380,3 @@ have made our sleepless nights possible.
 
 Thanks,
 The VMSperl group
-
-
----------------------------------------------------------------------------
-[Here's the pre-5.004_04 version of README.vms, for the record.]
-
-Last revised: 19-Jan-1996 by Charles Bailey  bailey@genetics.upenn.edu
-
-The VMS port of Perl is still under development.  At this time, the Perl
-binaries built under VMS handle internal operations properly, for the most
-part, as well as most of the system calls which have close equivalents under
-VMS. There are still some incompatibilities in process handling (e.g the
-fork/exec model for creating subprocesses doesn't do what you might expect
-under Unix), and there remain some file handling differences from Unix.  Over
-the longer term, we'll try to get many of the useful VMS system services
-integrated as well, depending on time and people available.  Of course, if
-you'd like to add something yourself, or join the porting team, we'd love to
-have you!
-
-The current sources and build procedures have been tested on a VAX using VAXC
-and DECC, and on an AXP using DECC.  If you run into problems with other
-compilers, please let us know.
-
-Note to DECC users: Some early versions of the DECCRTL contained a few bugs
-which affect Perl performance:
-    - Newlines are lost on I/O through pipes, causing lines to run together.
-      This shows up as RMS RTB errors when reading from a pipe.  You can
-      work around this by having one process write data to a file, and
-      then having the other read the file, instead of the pipe.  This is
-      fixed in version 4 of DECC.
-    - The modf() routine returns a non-integral value for some values above
-      INT_MAX; the Perl "int" operator will return a non-integral value in
-      these cases.  This is fixed in version 4 of DECC.
-    - On the AXP, if SYSNAM privilege is enabled, the CRTL chdir() routine 
-      changes the process default device and directory permanently, even
-      though the call specified that the change should not persist after
-      Perl exited.  This is fixed by DEC CSC patch AXPACRT04_061.
-
-* Other software required
-
-At the moment, in addition to basic VMS, you'll need two things:
-   - a C compiler: VAXC, DECC, or gcc for the VAX; DECC for the AXP
-   - a make tool: DEC's MMS (version 2.6 or later) or the free analog MMK
-     (available from ftp.spc.edu), or a standard make utility (e.g. GNU make,
-     also available from ftp.spc.edu).
-In addition, you may include socket support if you have an IP stack running
-on your system.  See the topic "Socket support" for more information.
-
-* Socket support
-
-Perl includes a number of IP socket routines among its builtin functions,
-which are available if you choose to compile Perl with socket support.  Since
-IP networking is an optional addition to VMS, there are several different IP
-stacks available, so it's difficult to automate the process of building Perl
-with socket support in a way which will work on all systems.  
-
-By default, Perl is built without IP socket support.  If you define the macro
-SOCKET when invoking MMK, however, socket support will be included.  As
-distributed, Perl for VMS includes support for the SOCKETSHR socket library,
-which is layered on MadGoat software's vendor-independent NETLIB interface. 
-This provides support for all socket calls used by Perl except the
-[g|s]etnet*() routines, which are replaced for the moment by stubs which
-generate a fatal error if a Perl script attempts to call one of these routines. 
-Both SOCKETSHR and NETLIB are available from MadGoat ftp sites, such as
-ftp.spc.edu or ftp.wku.edu.
-
-You can link Perl directly to your TCP/IP stack's library, *as long as* it
-supplies shims for stdio routines which will properly handle both sockets and
-normal file descriptors.  This is necessary because Perl does not distinguish
-between the two, and will try to make normal stdio calls such as read() and
-getc() on socket file descriptors.  If you'd like to link Perl directly to
-your IP stack, then make the following changes:
-  - In Descrip.MMS, locate the section beginning with .ifdef SOCKET, and
-    change the SOCKLIB macro so that it translates to  the filespec of your
-    IP stack's socket library.  This will be added to the RTL options file.
-  - Edit the file SockAdapt.H in the [.VMS] subdirectory so that it
-    includes the Socket.H, In.H, Inet.H, NetDb.H, and, if necessary,
-    Errno.H header files for your IP stack, or so that it declares the
-    standard TCP/IP constants and data structures appropriately.  (See
-    the distributed copy of SockAdapt.H for a collection of the structures
-    needed by Perl itself, and [.ext.Socket]Socket.xs for a list of the
-    constants used by the Socket extension, if you elect to built it.)
-    You should also define any logical names necessary for your C compiler
-    to find these files before invoking MM[KS] to build Perl.
-  - Edit the file SockAdapt.C in the [.VMS] subdirectory so that it
-    contains routines which substitute for any IP library routines
-    required by Perl which your IP stack does not provide.  This may
-    require a little trial and error; we'll try to compile a complete
-    list soon of socket routines required by Perl.
-
-
-* Building Perl under VMS
-
-Since you're reading this, presumably you've unpacked the Perl distribution
-into its directory tree, in which you will find a [.vms] subdirectory below
-the directory in which this file is found.  If this isn't the case, then you'll
-need to unpack the distribution properly, or manually edit Descrip.MMS or
-the VMS Makefile to alter directory paths as necessary.  (I'd advise using the 
-`normal' directory tree, at least for the first time through.)  This
-subdirectory contains several files, among which are the following:
-  Config.VMS     - A template Config.H set up for VMS.
-  Descrip.MMS    - The MMS/MMK dependency file for building Perl
-  GenConfig.Pl   - A Perl script to generate Config.SH retrospectively
-                   from Config.VMS, since the Configure shell script which
-                   normally generates Config.SH doesn't run under VMS.
-  GenOpt.Com     - A little DCL procedure used to write some linker options
-                   files, since not all make utilities can do this easily.
-  Gen_ShrFls.Pl  - A Perl script which generates linker options files and
-                   MACRO declarations for PerlShr.Exe.
-  Makefile       - The make dependency file for building Perl  
-  MMS2Make.Pl    - A Perl script used to generate Makefile from Descrip.MMS
-  PerlVMS.pod    - Documentation for VMS-specific behavior of Perl
-  Perly_[CH].VMS - Versions of the byacc output from Perl's grammar,
-                   modified to include VMS-specific C compiler options
-  SockAdapt.[CH] - C source code used to integrate VMS TCP/IP support
-  Test.Com       - DCL driver for Perl regression tests
-  VMSish.H       - C header file containing VMS-specific definitions
-  VMS.C          - C source code for VMS-specific routines
-  VMS_Yfix.Pl    - Perl script to convert Perly.[CH] to Perly_[CH].VMS
-  WriteMain.Pl   - Perl script to generate Perlmain.C
-The [.Ext...] directories contain VMS-specific extensions distributed with
-Perl.  There may also be other files in [.VMS...] pertaining to features under
-development; for the most part, you can ignore them.  Note that packages in
-[.ext.*] are not built with Perl by default; you build the ones you want
-once the basic Perl build is complete (see the perlvms docs for instructions
-on building extensions.)
-
-Config.VMS and Decrip.MMS/Makefile are set up to build a version of Perl which
-includes all features known to work when this release was assembled.  If you
-have code at your site which would support additional features (e.g. emulation
-of Unix system calls), feel free to make the appropriate changes to these
-files.  (Note: Do not use or edit config.h in the main Perl source directory;
-it is superseded by the current Config.VMS during the build.)  You may also
-wish to make site-specific changes to Descrip.MMS or Makefile to reflect local
-conventions for naming of files, etc.
-
-There are several pieces of system-specific information which become part of
-the Perl Config extension.  Under VMS, the data for Config are generated by the
-script GenConfig.Pl in the [.VMS] subdirectory.  It tries to ascertain the
-necessary information from various files, or from the system itself, and
-generally does the right thing.  There is a list of hard-coded values at the
-end of this script which specifies items that are correct for most VMS systems,
-but may be incorrect for you, if your site is set up in an unusual fashion.  If
-you're familiar with Perl's Config extension, feel free to edit these values as
-necessary.  If this doesn't mean much to you, don't worry -- the information is
-probably correct, and even if it's not, none of these parameters affect your
-ability to build or run Perl.  You'll only get the wrong answer if you ask for
-it specifically from Config.
-
-Examine the information at the beginning of Descrip.MMS for information about
-specifying alternate C compilers or building a version of Perl with debugging
-support.  For instance, if you want to use DECC, you'll need to include the
-/macro="decc=1" qualifier to MMK  (If you're using make, these options are not
-supported.)  If you're on an AXP system, define the macro __AXP__ (MMK does
-this for you), and DECC will automatically be selected.
-
-To start the build, set default to the main source directory.  Since
-Descrip.MMS assumes that VMS commands have their usual meaning, and makes use
-of command-line macros, you may want to be certain that you haven't defined DCL
-symbols which would interfere with the build.  Then, if you are using MMS or
-MMK, say
-$ MMS/Descrip=[.VMS] ! or MMK
-(N.B. If you are using MMS, you must use version 2.6 or later; a bug in
-earlier versions produces malformed cc command lines.)  If you are using a
-version of make, say
-$ Make -f [.VMS]Makefile
-Note that the Makefile doesn't support conditional compilation, is
-set up to use VAXC on a VAX, and does not include socket support.  You can
-either edit the Makefile by hand, using Descrip.MMS as a guide, or use the
-Makefile to build Miniperl.Exe, and then run the Perl script MMS2Make.pl,
-found in the [.VMS] subdirectory, to generate a new Makefile with the options
-appropriate to your site.
-
-If you are using MM[SK], and you decide to rebuild Perl with a different set
-of parameters (e.g. changing the C compiler, or adding socket support), be
-sure to say
-$ MMK/Descrip=[.VMS] realclean
-first, in order to remove files generated during the previous build.  If
-you omit this step, you risk ending up with a copy of Perl which
-composed partially of old files and partially of new ones, which may lead
-to strange effects when you try to run Perl.
-
-A bug in some early versions of the DECC RTL on the AXP causes newlines
-to be lost when writing to a pipe.  A different bug in some patched versions
-of DECC 4.0 for VAX can also scramble preprocessor output.  Finally, gcc 2.7.2
-has yet another preprocessor bug, which causes line breaks to be inserted
-into the output at inopportune times.  Each of these bugs causes Gen_ShrFls.pl
-to fail, since it can't parse the preprocessor output to identify global
-variables and routines.  This problem is generally manifested as missing
-global symbols when linking PerlShr.Exe or Perl.Exe.  You can work around
-it by defining the macro PIPES_BROKEN when you invoke MMS or MMK.
-
-
-This will build the following files:
-  Miniperl.Exe        - a stand-alone version of without any extensions.
-                        Miniperl has all the intrinsic capabilities of Perl,
-                        but cannot make use of the DynaLoader or any
-                        extensions which use XS code.
-  PerlShr.Exe         - a shareable image containing most of Perl's internal
-                        routines and global variables.  Perl.Exe is linked to
-                        this image, as are all dynamic extensions, so everyone's
-                        using the same set of global variables and routines.
-  Perl.Exe            - the main Perl executable image.  It's contains the
-                        main() routine, plus code for any statically linked
-                        extensions.
-  PerlShr_Attr.Opt    - A linker options file which specifies psect attributes
-                        matching those in PerlShr.Exe.  It should be used when
-                        linking images against PerlShr.Exe
-  PerlShr_Bld.Opt     - A linker options file which specifies various things
-                        used to build PerlShr.Exe.  It should be used when
-                        rebuilding PerlShr.Exe via MakeMaker-produced
-                        Descrip.MMS files for static extensions.
-  c2ph                - Perl program which generates template code to access
-                        C struct members from Perl.
-  h2ph                - Perl program which generates template code to access
-                        #defined constants in a C header file from Perl,
-                        using the "old-style" interface.  (Largely supplanted
-                        by h2xs.)
-  h2xs                - Perl program which generates template files for creating
-                        XSUB extensions, optionally beginning with the #defined
-                        constants in a C header file.
-  [.lib.pod]perldoc   - A Perl program which locates and displays documentation
-                        for Perl and its extensions.
-  [.Lib]Config.pm     - the Perl extension which saves configuration information
-                        about Perl and your system.
-  [.Lib]DynaLoader.pm - The Perl extension which performs dynamic linking of
-                        shareable images for extensions.
-  Several subdirectories under [.Lib] containing preprocessed files or
-                        site-specific files.
-There are, of course, a number of other files created for use during the build. 
-Once you've got the binaries built, you may wish to `build' the `tidy' or
-`clean' targets to remove extra files.
-
-If you run into problems during the build, you can get help from the VMSPerl
-or perl5-porters mailing lists (see below).  When you report the problem,
-please include the following information:
-  - The version of Perl you're trying to build.  Please include any
-    "letter" patchlevel, in addition to the version number.  If the
-    build successfully created Miniperl.Exe, you can check this by
-    saying '$ MCR Sys$Disk:[]Miniperl -v'.  Also, please mention
-    where you obtained the distribution kit; in particular, note
-    whether you were using a basic Perl kit or the VMS test kit
-    (see below).
-  - The exact command you issued to build Perl.
-  - A copy of all error messages which were generated during the build.
-    Please include enough of the build log to establish the context of
-    the error messages.
-  - A summary of your configuration.  If the build progressed far enough
-    to generate Miniperl.Exe and [.Lib]Config.pm, you can obtain this
-    by saying '$ MCR Sys$Disk:[]Miniperl "-V"' (note the "" around -V).
-    If not, then you can say '$ MMK/Descrip=[.VMS] printconfig' to
-    produce the summary.
-This may sound like a lot of information to send, but it'll often make
-it easier for someone to spot the problem, instead of having to give
-a spectrum of possibilities.
-  
-
-
-* Installing Perl once it's built
-
-Once the build is complete, you'll need to do the following:
-  - Put PerlShr.Exe in a common directory, and make it world-readable.
-    If you place it in a location other than Sys$Share, you'll need to
-    define the logical name PerlShr to point to the image.  (If you're
-    installing on a VMScluster, be sure that each node is using the
-    copy of PerlShr you expect [e.g. if you put PerlShr.Exe in Sys$Share,
-    do they all share Sys$Share?]).
-  - Put Perl.Exe in a common directory, and make it world-executable.
-  - Define a foreign command to invoke Perl, using a statement like
-    $ Perl == "$dev:[dir]Perl.Exe"
-  - Create a world-readable directory tree for Perl library modules,
-    scripts, and what-have-you, and define PERL_ROOT as a rooted logical
-    name pointing to the top of this tree (i.e. if your Perl files were
-    going to live in DKA1:[Util.Perl5...], then you should
-      $ Define/Translation=Concealed Perl_Root DKA1:[Util.Perl5.]
-    (Be careful to follow the rules for rooted logical names; in particular,
-    remember that a rooted logical name cannot have as its device portion
-    another rooted logical name - you've got to supply the actual device name
-    and directory path to the root directory.)
-  - Place the files from the [.lib...] directory tree in the distribution
-    package into a [.lib...] directory tree off the root directory described
-    above.
-  - Most of the Perl documentation lives in the [.pod] subdirectory, and
-    is written in a simple markup format which can be easily read.  In this
-    directory as well are pod2man and pod2html translators to reformat the
-    docs for common display engines; a pod2hlp translator is under development.
-    These files are copied to [.lib.pod] during the installation.
-  - Define a foreign command to execute perldoc, such as
-    $ Perldoc == "''Perl' Perl_Root:[lib.pod]Perldoc -t"
-    This will allow users to retrieve documentation using Perldoc.  For
-    more details, say "perldoc perldoc".
-That's it.
-
-If you run into a bug in Perl, please submit a bug report.  The PerlBug
-program, found in the [.lib] directory, will walk you through the process
-of assembling the necessary information into a bug report, and sending
-of to the Perl bug reporting address, perlbug@perl.com.
-
-* For more information
-
-If you're interested in more information on Perl in general, you may wish to
-consult the Usenet newsgroups comp.lang.perl.announce and comp.lang.perl.misc.
-The FAQ for these groups provides pointers to other online sources of
-information, as well as books describing Perl in depth.
-
-If you're interested in up-to-date information on Perl development and
-internals, you might want to subscribe to the perl5-porters mailing list.  You
-can do this by sending a message to perl5-porters-request@nicoh.com, containing
-the single line
-subscribe perl5-porters
-This is a high-volume list at the moment (>50 messages/day).
-
-If you're interested in ongoing information about the VMS port, you can
-subscribe to the VMSPerl mailing list by sending a request to
-vmsperl-request@genetics.upenn.edu, containing the single line
-subscribe VMSPerl
-as the body of the message.  And, as always, we welcome any help or code you'd
-like to offer - you can send mail to bailey@genetics.upenn.edu or directly to
-the VMSPerl list at vmsperl@genetics.upenn.edu.
-
-Finally, if you'd like to try out the latest changes to VMS Perl, you can
-retrieve a test distribution kit by anonymous ftp from genetics.upenn.edu, in
-the file [.perl5]perl5_ppp_yymmddx.zip, where "ppp" is the current Perl
-patchlevel, and "yymmddx" is a sequence number indicating the date that
-particular kit was assembled.  In order to make retrieval convenient, this
-kit is also available by the name Perl5_VMSTest.Zip.  These test kits contain
-"unofficial" patches from the perl5-porters group, test patches for important
-bugs, and VMS-specific fixes and improvements which have occurred since the
-last Perl release.  Most of these changes will be incorporated in the next
-release of Perl, but until Larry Wall's looked at them and said they're OK,
-none of them should be considered official.
-
-Good luck using Perl.  Please let us know how it works for you - we can't
-guarantee that we'll be able to fix bugs quickly, but we'll try, and we'd
-certainly like to know they're out there.
-
-
-* Acknowledgements
-
-There are, of course, far too many people involved in the porting and testing
-of Perl to mention everyone who deserves it, so please forgive us if we've
-missed someone.  That said, special thanks are due to the following:
-  Tim Adye <T.J.Adye@rl.ac.uk>
-     for the VMS emulations of getpw*()
-  David Denholm <denholm@conmat.phys.soton.ac.uk>
-     for extensive testing and provision of pipe and SocketShr code,
-  Mark Pizzolato <mark@infocomm.com>
-     for the getredirection() code
-  Rich Salz <rsalz@bbn.com>
-     for readdir() and related routines
-  Peter Prymmer <pvhp@lns62.lns.cornell.edu)
-     for extensive testing, as well as development work on
-     configuration and documentation for VMS Perl,
-  the Stanford Synchrotron Radiation Laboratory and the
-     Laboratory of Nuclear Studies at Cornell University for
-     the the opportunity to test and develop for the AXP,
-and to the entire VMSperl group for useful advice and suggestions.  In addition
-the perl5-porters, especially Andy Dougherty <doughera@lafcol.lafayette.edu>
-and Tim Bunce <Tim.Bunce@ig.co.uk>,  deserve credit for their creativity and
-willingness to work with the VMS newcomers.  Finally, the greatest debt of
-gratitude is due to Larry Wall <larry@wall.org>, for having the ideas which
-have made our sleepless nights possible.
-
-Thanks,
-The VMSperl group