[PATCH: 5.6.1 trial 2 && perl@8671] podify README.vmesa

Hello,

The following patch podifies README.vmesa in a manner similar to the
podified README.os390.  It may take some time before the "known 
test failure" list can be compiled hence I am taking this opportunity to
get the patch in before the release deadline.

Files affected:

     win32/Makefile
     win32/makefile.mk
     README.vmesa

Note that here I have tweaked the double perlos2.pod and the added
perlos390.pod in this patch, changes that might have already been put into
the repository if the patch from:

 http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2001-01/msg00971.html

which was applicable to perl@8482 and Jarkko acknowledged as having been
applied in:

 http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2001-01/msg01019.html

But did not appear in the 5.6.1-trial2 kit that I have taken the diff
w.r.t.  Note the ^M ought to be at the end of each line in the win32/*
files:

diff -ru perl-5.6.1-TRIAL2.orig/README.vmesa perl-5.6.1-TRIAL2/README.vmesa
--- perl-5.6.1-TRIAL2.orig/README.vmesa	Wed Jan 31 07:56:47 2001
+++ perl-5.6.1-TRIAL2/README.vmesa	Thu Feb  8 11:27:23 2001
@@ -1,4 +1,20 @@
-README.vmesa
+
+This document is written in pod format hence there are punctuation
+characters in odd places.  Do not worry, you've apparently got
+the ASCII->EBCDIC translation worked out correctly.  You can read
+more about pod in pod/perlpod.pod or the short summary in the
+INSTALL file.
+
+=head1 NAME
+
+README.vmesa - building and installing Perl for VM/ESA.
+
+=head1 SYNOPSIS
+
+This document will help you Configure, build, test and install Perl
+on VM/ESA.
+
+=head1 DESCRIPTION
 
 This is a fully ported perl for VM/ESA 2.3.0.  It may work on
 other versions, but that's the one we've tested it on.
@@ -10,48 +26,75 @@
 installed by default).  You may need to worry about the networking
 configuration files discussed in the last bullet below.
 
+=head2 Unpacking
+
 To extract an ASCII tar archive on VM/ESA, try this:
 
    pax -o to=IBM-1047,from=ISO8859-1 -r < latest.tar
 
+=head2 Setup and utilities
+
 GNU make for VM/ESA, which may be required for the build of perl,
 is available from:
 
   http://pucc.princeton.edu/~neale/vmoe.html
 
+=head2 Configure
+
 Once you've unpacked the distribution, run Configure (see INSTALL for
 full discussion of the Configure options), and then run make, then
 "make test" then "make install" (this last step may require UID=0
-privileges)
+privileges).
 
 There is a "hints" file for vmesa that specifies the correct values
-for most things.  Some things to watch out for are
+for most things.  Some things to watch out for are:
 
-	- this port does support dynamic loading but it's not had much testing
+=over 4
 
+=item *
+
+this port does support dynamic loading but it's not had much testing
+
+=item *
 	- Don't turn on the compiler optimization flag "-O".  There's
 	  a bug in the compiler (APAR PQ18812) that generates some bad code
 	  the optimizer is on.
 
+=item *
 	- As VM/ESA doesn't fully support the fork() API programs relying on
 	  this call will not work. I've replaced fork()/exec() with spawn()
 	  and the standalone exec() with spawn(). This has a side effect when
 	  opening unnamed pipes in a shell script: there is no child process
 	  generated under.
 
-	- At the moment the hints file for VM/ESA basically bypasses all of the
-	  automatic configuration process. This is because Configure relies on:
-	  1. The header files living in the Byte File System (you could put the
-	     there if you want;
-	  2. The C preprocessor including the #include statements in the
-	     preprocessor output (.i) file.
+=item *
+
+At the moment the hints file for VM/ESA basically bypasses all of the
+automatic configuration process.  This is because Configure relies on:
+1. The header files living in the Byte File System (you could put the
+there if you want); 2. The C preprocessor including the #include 
+statements in the preprocessor output (.i) file.
+
+=back
+
+=head2 testing anomalies
+
+The `make test` step runs a Perl Verification Procedure, usually before
+installation.  As the 5.6.1 kit was was being assembled
+the following "failures" were known to appear on some machines
+during `make test` (mostly due to ASCII vs. EBCDIC conflicts),
+your results may differ:
+
+[the list of failures being compiled]
+
+=head2 Usage Hints
 	
 When using perl on VM/ESA please keep in mind that the EBCDIC and ASCII
 character sets are different.  Perl builtin functions that may behave
 differently under EBCDIC are mentioned in the perlport.pod document.
 
 OpenEdition (UNIX System Services) does not (yet) support the #! means
-of script invokation.
+of script invocation.
 See:
 
     head `whence perldoc`
@@ -59,6 +102,16 @@
 for an example of how to use the "eval exec" trick to ask the shell to
 have perl run your scripts for you.
 
+=head1 AUTHORS
+
+Neale Ferguson.
+
+=head1 SEE ALSO
+
+L<INSTALL>, L<perlport>, L<perlebcdic>.
+
+=head2 Mailing list
+
 If you are interested in the VM and OS/390 ports of perl then see the
 perl-mvs mailing list: The Perl Institute (http://www.perl.org/)
 maintains a mailing list of interest to all folks building and/or
@@ -68,9 +121,14 @@
 
 to majordomo@perl.org.
 
-Regression tests: as the 5.005 kit was was being assembled
-the following "failures" were known to appear on some machines
-during `make test` (mostly due to ASCII vs. EBCDIC conflicts),
-your results may differ:
+   See also:
+
+    http://lists.perl.org/showlist.cgi?name=perl-mvs
+
+There are web archives of the mailing list at:
+
+    http://www.xray.mpe.mpg.de/mailing-lists/perl-mvs/
+    http://archive.develooper.com/perl-mvs@perl.org/
+
+=cut
 
-[the list of failures being compiled]
diff -ru perl-5.6.1-TRIAL2.orig/win32/Makefile perl-5.6.1-TRIAL2/win32/Makefile
--- perl-5.6.1-TRIAL2.orig/win32/Makefile	Wed Jan 31 07:58:54 2001
+++ perl-5.6.1-TRIAL2/win32/Makefile	Thu Feb  8 12:47:07 2001
@@ -1004,6 +1004,8 @@
 	copy ..\README.hpux .\perlhpux.pod
 	copy ..\README.machten .\perlmachten.pod
 	copy ..\README.os2 .\perlos2.pod
+	copy ..\README.os390 .\perlos390.pod
+	copy ..\README.vmesa .\perlvmesa.pod
 	copy ..\vms\perlvms.pod .\perlvms.pod
 	copy ..\README.win32 .\perlwin32.pod
 	$(MAKE) -f ..\win32\pod.mak converters
diff -ru perl-5.6.1-TRIAL2.orig/win32/makefile.mk perl-5.6.1-TRIAL2/win32/makefile.mk
--- perl-5.6.1-TRIAL2.orig/win32/makefile.mk	Wed Jan 31 07:58:54 2001
+++ perl-5.6.1-TRIAL2/win32/makefile.mk	Thu Feb  8 12:46:17 2001
@@ -1217,7 +1217,8 @@
 	copy ..\README.hpux ..\pod\perlhpux.pod
 	copy ..\README.machten ..\pod\perlmachten.pod
 	copy ..\README.os2 ..\pod\perlos2.pod
-	copy ..\README.os2 ..\pod\perlos2.pod
+	copy ..\README.os390 ..\pod\perlos390.pod
+	copy ..\README.vmesa ..\pod\perlvmesa.pod
 	copy ..\vms\perlvms.pod ..\pod\perlvms.pod
 	cd ..\pod && $(MAKE) -f ..\win32\pod.mak converters
 	$(PERLEXE) $(PL2BAT) $(UTILS)
End of Patch.

Peter Prymmer

• [PATCH: 5.6.1 trial 2 && perl@8671] podify README.vmesa by Peter Prymmer