README.posix-bc podified from Thomas Dorner.

p4raw-id: //depot/cfgperl@6348

diff --git a/README.posix-bc b/README.posix-bc
index 1105f67..3dd8ea2 100644 (file)
--- a/README.posix-bc
+++ b/README.posix-bc
@@ -1,28 +1,43 @@
-This is a first ported perl for the POSIX subsystem in BS2000 VERSION
-'V121', OSD V3.1, POSIX Shell V03.1A55.  It may work on other
-versions, but that's the one we've tested it on.
+This document is written in pod format hence there are punctuation
+characters in 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.posix-bc - building and installing Perl for BS2000 POSIX.
+
+=head1 SYNOPSIS
+
+This document will help you Configure, build, test and install Perl
+on BS2000 in the POSIX subsystem.
+
+=head1 DESCRIPTION
+
+This is a ported perl for the POSIX subsystem in BS2000 VERSION OSD
+V3.1A.  It may work on other versions, but that's the one we've tested
+it on.
 
 You may need the following GNU programs in order to install perl:
 
-gzip:
+=head2 gzip
 
 We used version 1.2.4, which could be installed out of the box with
 one failure during 'make check'.
 
-bison:
+=head2 bison
 
 The yacc coming with BS2000 POSIX didn't work for us.  So we had to
 use bison.  We had to make a few changes to perl in order to use the
 pure (reentrant) parser of bison.  We used version 1.25, but we had to
 add a few changes due to EBCDIC.
 
-
-UNPACKING:
-==========
+=head2 Unpacking
 
 To extract an ASCII tar archive on BS2000 POSIX you need an ASCII
 filesystem (we used the mountpoint /usr/local/ascii for this).  Now
-you extract the archive in the ASCII filesystem without I/O-conversion:
+you extract the archive in the ASCII filesystem without
+I/O-conversion:
 
 cd /usr/local/ascii
 export IO_CONVERSION=NO
@@ -30,24 +45,20 @@ gunzip < /usr/local/src/perl.tar.gz | pax -r
 
 You may ignore the error message for the first element of the archive
 (this doesn't look like a tar archive / skipping to next file...),
-it's only the directory which will be made anyway.
+it's only the directory which will be created automatically anyway.
 
 After extracting the archive you copy the whole directory tree to your
-EBCDIC filesystem.  This time you use I/O-conversion:
+EBCDIC filesystem.  B<This time you use I/O-conversion>:
 
 cd /usr/local/src
 IO_CONVERSION=YES
 cp -r /usr/local/ascii/perl5.005_02 ./
 
-
-COMPILING:
-==========
+=head2 Compiling
 
 There is a "hints" file for posix-bc that specifies the correct values
 for most things.  The major problem is (of course) the EBCDIC character
-set.
-
-Configure did everything except the perl parser.
+set.  We have german EBCDIC version.
 
 Because of our problems with the native yacc we used GNU bison to
 generate a pure (=reentrant) parser for perly.y.  So our yacc is
@@ -85,16 +96,15 @@ We still use the normal yacc for a2p.y though!!!  We made a softlink
 called byacc to distinguish between the two versions:
 
 ln -s /usr/bin/yacc /usr/local/bin/byacc
- 
-We build perl using both GNU make and the native make.
 
+We build perl using GNU make.  We tried the native make once and it
+worked too.
 
-TESTING:
-========
+=head2 Testing
 
-We still got a few errors during 'make test'.  Some of them are the
-result of using bison.  Bison prints 'parser error' instead of 'syntax
-error', so we may ignore them.  The following list shows
+We still got a few errors during C<make test>.  Some of them are the
+result of using bison.  Bison prints I<parser error> instead of I<syntax
+error>, so we may ignore them.  The following list shows
 our errors, your results may differ:
 
 op/numconvert.......FAILED tests 1409-1440
@@ -108,20 +118,45 @@ lib/complex.........FAILED tests 267, 487
 lib/dumper..........FAILED tests 43, 45
 Failed 11/231 test scripts, 95.24% okay. 57/10595 subtests failed, 99.46% okay.
 
-INSTALLING:
-===========
+=head2 Install
 
 We have no nroff on BS2000 POSIX (yet), so we ignored any errors while
 installing the documentation.
 
 
-USING PERL:
-===========
+=head2 Using Perl
 
 BS2000 POSIX doesn't support the shebang notation
-('#!/usr/local/bin/perl'), so you have to use the following lines
+(C<#!/usr/local/bin/perl>), so you have to use the following lines
 instead:
 
 : # use perl
     eval 'exec /usr/local/bin/perl -S $0 ${1+"$@"}'
         if $running_under_some_shell;
+
+=head1 AUTHORS
+
+Thomas Dorner
+
+=head1 SEE ALSO
+
+L<INSTALL>, L<perlport>.
+
+=head2 Mailing list
+
+The Perl Institute (http://www.perl.org/) maintains a perl-mvs mailing
+list of interest to all folks building and/or using perl on EBCDIC
+platforms.  To subscibe, send a message of:
+
+    subscribe perl-mvs
+
+to majordomo@perl.org.
+
+=head1 HISTORY
+
+This document was originally written by Thomas Dorner for the 5.005
+release of Perl.
+
+This document was podified for the 5.6 release of perl 11 July 2000.
+
+=cut