This is my patch patch.1g for perl5.001.

This patch only includes updates to the lib/ directory and
the removal of the pod/modpods.  The main things are the following:

	The modpods are now embedded in their corresponding .pm files.

	The Grand AutoLoader patch.

	Updates to lib/ExtUtils/xsubpp by Paul Marquess 
	<pmarquess@bfsec.bt.co.uk>.

	Minor changes to a very few modules and pods.


To apply, change to your perl directory, run the commands above, then
apply with 
    patch -p1 -N  < thispatch.

After you apply this patch, you should go on to apply patch.1h and
patch.1i before reConfiguring and building.

Patch and enjoy,

	Andy Dougherty			doughera@lafcol.lafayette.edu
	Dept. of Physics
	Lafayette College, Easton PA

Here's the file-by-file description:

lib/AnyDBM_File.pm
    Embedded pod.

lib/AutoLoader.pm
    Grand AutoLoader patch.

    Embedded pod.

lib/AutoSplit.pm
    Grand AutoLoader patch.

    Embedded pod.

    Skip pod sections when splitting .pm files.

lib/Benchmark.pm
lib/Carp.pm
lib/Cwd.pm
lib/English.pm
    Grand AutoLoader patch.

    Embedded pod.

lib/Exporter.pm
    Grand AutoLoader patch.

    Embedded pod.

    Update comments to match behavior.

lib/ExtUtils/MakeMaker.pm
    Include installation of .pod and .pm files.

    Space out documentation for better printing with pod2man.

lib/ExtUtils/xsubpp
    Patches from Paul Marquess <pmarquess@bfsec.bt.co.uk>, 22 May 1995.
    Now at version 1.4.

lib/File/Basename.pm
    Embedded pod.

lib/File/CheckTree.pm
    Embedded pod.

lib/File/Find.pm
    Embedded pod.

    Included finddepth pod too.

lib/FileHandle.pm
    Embedded pod.

lib/Getopt/Long.pm
    Embedded pod.

    Fixed PERMUTE order bug.

lib/Getopt/Std.pm
    Embedded pod.

    Caught accessing undefined element off end of @arg array.

lib/I18N/Collate.pm
lib/IPC/Open2.pm
lib/IPC/Open3.pm
lib/Net/Ping.pm
    Embedded pod.

lib/Term/Complete.pm
    Embedded pod.

    Changed name from complete to Complete to match documentation and
    exported name.

lib/Text/Abbrev.pm
    Embedded pod.

lib/Text/Tabs.pm
    Updated.

lib/integer.pm
lib/less.pm
lib/sigtrap.pm
lib/strict.pm
lib/subs.pm
    Embedded pod.

28 files changed, 1388 insertions, 57 deletions

diff --git a/lib/AnyDBM_File.pm b/lib/AnyDBM_File.pm
index ff9078652e..50acce412a 100644
--- a/lib/AnyDBM_File.pm
+++ b/lib/AnyDBM_File.pm
@@ -7,3 +7,86 @@ eval { require DB_File } ||
 eval { require GDBM_File } ||
 eval { require SDBM_File } ||
 eval { require ODBM_File };
+
+=head1 NAME
+
+AnyDBM_File - provide framework for multiple DBMs
+
+NDBM_File, ODBM_File, SDBM_File, GDBM_File - various DBM implementations
+
+=head1 SYNOPSIS
+
+    use AnyDBM_File;
+
+=head1 DESCRIPTION
+
+This module is a "pure virtual base class"--it has nothing of its own.
+It's just there to inherit from one of the various DBM packages.  It
+prefers ndbm for compatibility reasons with Perl 4, then Berkeley DB (See
+L<DB_File>), GDBM, SDBM (which is always there--it comes with Perl), and
+finally ODBM.   This way old programs that used to use NDBM via dbmopen()
+can still do so, but new ones can reorder @ISA:
+
+    @AnyDBM_File::ISA = qw(DB_File GDBM_File NDBM_File);
+
+Note, however, that an explicit use overrides the specified order:
+
+    use GDBM_File;
+    @AnyDBM_File::ISA = qw(DB_File GDBM_File NDBM_File);
+
+will only find GDBM_File.
+
+Having multiple DBM implementations makes it trivial to copy database formats:
+
+    use POSIX; use NDBM_File; use DB_File;
+    tie %newhash,  DB_File, $new_filename, O_CREAT|O_RDWR;
+    tie %oldhash,  NDBM_File, $old_filename, 1, 0;
+    %newhash = %oldhash;
+
+=head2 DBM Comparisons
+
+Here's a partial table of features the different packages offer:
+
+                         odbm    ndbm    sdbm    gdbm    bsd-db
+			 ----	 ----    ----    ----    ------
+ Linkage comes w/ perl   yes     yes     yes     yes     yes
+ Src comes w/ perl       no      no      yes     no      no
+ Comes w/ many unix os   yes     yes[0]  no      no      no
+ Builds ok on !unix      ?       ?       yes     yes     ?
+ Code Size               ?       ?       small   big     big
+ Database Size           ?       ?       small   big?    ok[1]
+ Speed                   ?       ?       slow    ok      fast
+ FTPable                 no      no      yes     yes     yes
+ Easy to build          N/A     N/A      yes     yes     ok[2]
+ Size limits             1k      4k      1k[3]   none    none
+ Byte-order independent  no      no      no      no      yes
+ Licensing restrictions  ?       ?       no      yes     no
+
+
+=over 4
+
+=item [0] 
+
+on mixed universe machines, may be in the bsd compat library,
+which is often shunned.
+
+=item [1] 
+
+Can be trimmed if you compile for one access method.
+
+=item [2] 
+
+See L<DB_File>. 
+Requires symbolic links.  
+
+=item [3] 
+
+By default, but can be redefined.
+
+=back
+
+=head1 SEE ALSO
+
+dbm(3), ndbm(3), DB_File(3)
+
+=cut
diff --git a/lib/AutoLoader.pm b/lib/AutoLoader.pm
index 92109a3681..449498c367 100644
--- a/lib/AutoLoader.pm
+++ b/lib/AutoLoader.pm
@@ -1,6 +1,24 @@
 package AutoLoader;
 use Carp;
 
+=head1 NAME
+
+AutoLoader - load functions only on demand
+
+=head1 SYNOPSIS
+
+    package FOOBAR;
+    use Exporter;
+    use AutoLoader;
+    @ISA = (Exporter, AutoLoader);
+
+=head1 DESCRIPTION
+
+This module tells its users that functions in the FOOBAR package are to be
+autoloaded from F<auto/$AUTOLOAD.al>.  See L<perlsub/"Autoloading">.
+
+=cut
+
 AUTOLOAD {
     my $name = "auto/$AUTOLOAD.al";
     $name =~ s#::#/#g;
@@ -24,5 +42,23 @@ AUTOLOAD {
     }
     goto &$AUTOLOAD;
 }
+                            
+sub import
+{
+ my ($callclass, $callfile, $callline,$path,$callpack) = caller(0);
+ ($callpack = $callclass) =~ s#::#/#;
+ if (defined($path = $INC{$callpack . '.pm'}))
+  {
+   if ($path =~ s#^(.*)$callpack\.pm$#$1auto/$callpack/autosplit.ix# && -e $path) 
+    {
+     eval {require $path}; 
+     carp $@ if ($@);  
+    } 
+   else 
+    {
+     croak "Have not loaded $callpack.pm";
+    }
+  }
+}
 
 1;
diff --git a/lib/AutoSplit.pm b/lib/AutoSplit.pm
index a6422611bc..72f897d1b1 100644
--- a/lib/AutoSplit.pm
+++ b/lib/AutoSplit.pm
@@ -10,6 +10,19 @@ use Carp;
 @EXPORT = qw(&autosplit &autosplit_lib_modules);
 @EXPORT_OK = qw($Verbose $Keep $Maxlen $CheckForAutoloader $CheckModTime);
 
+=head1 NAME
+
+AutoSplit - split a package for autoloading
+
+=head1 DESCRIPTION
+
+This function will split up your program into files that the AutoLoader
+module can handle.  Normally only used to build autoloading Perl library
+modules, especially extensions (like POSIX).  You should look at how
+they're built out for details.
+
+=cut
+
 # for portability warn about names longer than $maxlen
 $Maxlen  = 8;	# 8 for dos, 11 (14-".al") for SYSVR3
 $Verbose = 1;	# 0=none, 1=minimal, 2=list .al files
@@ -83,7 +96,13 @@ sub autosplit_file{
     open(IN, "<$filename") || die "AutoSplit: Can't open $filename: $!\n";
     my($pm_mod_time) = (stat($filename))[9];
     my($autoloader_seen) = 0;
+    my($in_pod) = 0;
     while (<IN>) {
+	# Skip pod text.
+	$in_pod = 1 if /^=/;
+	$in_pod = 0 if /^=cut/;
+	next if ($in_pod || /^=cut/);
+
 	# record last package name seen
 	$package = $1 if (m/^\s*package\s+([\w:]+)\s*;/);
 	++$autoloader_seen if m/^\s*(use|require)\s+AutoLoader\b/;
@@ -199,7 +218,9 @@ sub autosplit_file{
 	    next if $names{substr($subname,0,$maxflen-3)};
 	    my($file) = "$autodir/$modpname/$_";
 	    print "  deleting $file\n" if ($Verbose>=2);
-	    unlink $file or carp "Unable to delete $file: $!";
+	    my($deleted,$thistime);  # catch all versions on VMS
+	    do { $deleted += ($thistime = unlink $file) } while ($thistime);
+	    carp "Unable to delete $file: $!" unless $deleted;
 	}
 	closedir(OUTDIR);
     }
@@ -207,7 +228,9 @@ sub autosplit_file{
     open(TS,">$al_idx_file") or
 	carp "AutoSplit: unable to create timestamp file ($al_idx_file): $!";
     print TS "# Index created by AutoSplit for $filename (file acts as timestamp)\n";
+    print TS "package $package;\n";
     print TS map("sub $_ ;\n", @subnames);
+    print TS "1;\n";
     close(TS);
 
     check_unique($package, $Maxlen, 1, @names);
diff --git a/lib/Benchmark.pm b/lib/Benchmark.pm
index a19caffdc8..40481f9662 100644
--- a/lib/Benchmark.pm
+++ b/lib/Benchmark.pm
@@ -1,5 +1,166 @@
 package Benchmark;
 
+=head1 NAME
+
+Benchmark - benchmark running times of code
+
+timethis - run a chunk of code several times
+
+timethese - run several chunks of code several times
+
+timeit - run a chunk of code and see how long it goes
+
+=head1 SYNOPSIS
+
+    timethis ($count, "code");
+
+    timethese($count, {
+	'Name1' => '...code1...',
+	'Name2' => '...code2...',
+    });
+
+    $t = timeit($count, '...other code...')
+    print "$count loops of other code took:",timestr($t),"\n";
+
+=head1 DESCRIPTION
+
+The Benchmark module encapsulates a number of routines to help you
+figure out how long it takes to execute some code.
+
+=head2 Methods
+
+=over 10
+
+=item new
+
+Returns the current time.   Example:
+
+    use Benchmark;
+    $t0 = new Benchmark;
+    # ... your code here ...
+    $t1 = new Benchmark;
+    $td = timediff($t1, $t0);
+    print "the code took:",timestr($dt),"\n";
+
+=item debug
+
+Enables or disable debugging by setting the C<$Benchmark::Debug> flag:
+
+    debug Benchmark 1; 
+    $t = timeit(10, ' 5 ** $Global ');
+    debug Benchmark 0; 
+
+=back
+
+=head2 Standard Exports
+
+The following routines will be exported into your namespace 
+if you use the Benchmark module:
+
+=over 10
+
+=item timeit(COUNT, CODE)
+
+Arguments: COUNT is the number of time to run the loop, and 
+the second is the code to run.  CODE may be a string containing the code,
+a reference to the function to run, or a reference to a hash containing 
+keys which are names and values which are more CODE specs.
+
+Side-effects: prints out noise to standard out.
+
+Returns: a Benchmark object.  
+
+=item timethis
+
+=item timethese
+
+=item timediff
+
+=item timestr
+
+=back
+
+=head2 Optional Exports
+
+The following routines will be exported into your namespace
+if you specifically ask that they be imported:
+
+=over 10
+
+clearcache
+
+clearallcache
+
+disablecache
+
+enablecache
+
+=back
+
+=head1 NOTES
+
+The data is stored as a list of values from the time and times
+functions: 
+
+      ($real, $user, $system, $children_user, $children_system)
+
+in seconds for the whole loop (not divided by the number of rounds).
+
+The timing is done using time(3) and times(3).
+
+Code is executed in the caller's package.
+
+Enable debugging by:  
+
+    $Benchmark::debug = 1;
+
+The time of the null loop (a loop with the same
+number of rounds but empty loop body) is subtracted
+from the time of the real loop.
+
+The null loop times are cached, the key being the
+number of rounds. The caching can be controlled using
+calls like these:
+
+    clearcache($key); 
+    clearallcache();
+
+    disablecache(); 
+    enablecache();
+
+=head1 INHERITANCE
+
+Benchmark inherits from no other class, except of course
+for Exporter.
+
+=head1 CAVEATS
+
+The real time timing is done using time(2) and
+the granularity is therefore only one second.
+
+Short tests may produce negative figures because perl
+can appear to take longer to execute the empty loop 
+than a short test; try: 
+
+    timethis(100,'1');
+
+The system time of the null loop might be slightly
+more than the system time of the loop with the actual
+code and therefore the difference might end up being < 0.
+
+More documentation is needed :-( especially for styles and formats.
+
+=head1 AUTHORS
+
+Jarkko Hietaniemi <Jarkko.Hietaniemi@hut.fi>,
+Tim Bunce <Tim.Bunce@ig.co.uk>
+
+=head1 MODIFICATION HISTORY
+
+September 8th, 1994; by Tim Bunce.
+
+=cut
+
 # Purpose: benchmark running times of code.
 #
 #
diff --git a/lib/Carp.pm b/lib/Carp.pm
index c847b77b36..ba21d9c625 100644
--- a/lib/Carp.pm
+++ b/lib/Carp.pm
@@ -1,5 +1,29 @@
 package Carp;
 
+=head1 NAME
+
+carp - warn of errors (from perspective of caller)
+
+croak - die of errors (from perspective of caller)
+
+confess - die of errors with stack backtrace
+
+=head1 SYNOPSIS
+
+    use Carp;
+    croak "We're outta here!";
+
+=head1 DESCRIPTION
+
+The Carp routines are useful in your own modules because
+they act like die() or warn(), but report where the error
+was in the code they were called from.  Thus if you have a 
+routine Foo() that has a carp() in it, then the carp() 
+will report the error as occurring where Foo() was called, 
+not where carp() was called.
+
+=cut
+
 # This package implements handy routines for modules that wish to throw
 # exceptions outside of the current package.
 
diff --git a/lib/Cwd.pm b/lib/Cwd.pm
index 20b175c81d..af1167dfc8 100644
--- a/lib/Cwd.pm
+++ b/lib/Cwd.pm
@@ -3,6 +3,35 @@ require 5.000;
 require Exporter;
 use Config;
 
+=head1 NAME
+
+getcwd - get pathname of current working directory
+
+=head1 SYNOPSIS
+
+    require Cwd;
+    $dir = Cwd::getcwd();
+
+    use Cwd;
+    $dir = getcwd();
+
+    use Cwd 'chdir';
+    chdir "/tmp";
+    print $ENV{'PWD'};
+
+=head1 DESCRIPTION
+
+The getcwd() function re-implements the getcwd(3) (or getwd(3)) functions
+in Perl.  If you ask to override your chdir() built-in function, then your
+PWD environment variable will be kept up to date.  (See
+L<perlsub/Overriding builtin functions>.)
+
+The fastgetcwd() function looks the same as getcwd(), but runs faster.
+It's also more dangerous because you might conceivably chdir() out of a
+directory that you can't chdir() back into.
+
+=cut
+
 @ISA = qw(Exporter);
 @EXPORT = qw(getcwd fastcwd);
 @EXPORT_OK = qw(chdir);
diff --git a/lib/English.pm b/lib/English.pm
index d40d28af7d..d82ba2cf52 100644
--- a/lib/English.pm
+++ b/lib/English.pm
@@ -3,6 +3,32 @@ package English;
 require Exporter;
 @ISA = (Exporter);
 
+=head1 NAME
+
+English - use nice English (or awk) names for ugly punctuation variables
+
+=head1 SYNOPSIS
+
+    use English;
+    ...
+    if ($ERRNO =~ /denied/) { ... }
+
+=head1 DESCRIPTION
+
+This module provides aliases for the built-in variables whose
+names no one seems to like to read.  Variables with side-effects
+which get triggered just by accessing them (like $0) will still 
+be affected.
+
+For those variables that have an B<awk> version, both long
+and short English alternatives are provided.  For example, 
+the C<$/> variable can be referred to either $RS or 
+$INPUT_RECORD_SEPARATOR if you are using the English module.
+
+See L<perlvar> for a complete list of these.
+
+=cut
+
 local $^W = 0;
 
 # Grandfather $NAME import
diff --git a/lib/Exporter.pm b/lib/Exporter.pm
index add5657fac..ca1ff3547c 100644
--- a/lib/Exporter.pm
+++ b/lib/Exporter.pm
@@ -2,31 +2,40 @@ package Exporter;
 
 =head1 Comments
 
-If the first entry in an import list begins with /, ! or : then
-treat the list as a series of specifications which either add to
-or delete from the list of names to import. They are processed
-left to right. Specifications are in the form:
+If the first entry in an import list begins with !, : or / then the
+list is treated as a series of specifications which either add to or
+delete from the list of names to import. They are processed left to
+right. Specifications are in the form:
 
-    [!]/pattern/    All names in @EXPORT and @EXPORT_OK which match
     [!]name         This name only
-    [!]:tag         All names in $EXPORT_TAGS{":tag"}
     [!]:DEFAULT     All names in @EXPORT
+    [!]:tag         All names in $EXPORT_TAGS{tag} anonymous list
+    [!]/pattern/    All names in @EXPORT and @EXPORT_OK which match
 
-e.g., Foo.pm defines:
+A leading ! indicates that matching names should be deleted from the
+list of names to import.  If the first specification is a deletion it
+is treated as though preceded by :DEFAULT. If you just want to import
+extra names in addition to the default set you will still need to
+include :DEFAULT explicitly.
+
+e.g., Module.pm defines:
 
     @EXPORT      = qw(A1 A2 A3 A4 A5);
     @EXPORT_OK   = qw(B1 B2 B3 B4 B5);
-    %EXPORT_TAGS = (':T1' => [qw(A1 A2 B1 B2)], ':T2' => [qw(A1 A2 B3 B4)]);
+    %EXPORT_TAGS = (T1 => [qw(A1 A2 B1 B2)], T2 => [qw(A1 A2 B3 B4)]);
 
     Note that you cannot use tags in @EXPORT or @EXPORT_OK.
     Names in EXPORT_TAGS must also appear in @EXPORT or @EXPORT_OK.
 
 Application says:
 
-    use Module qw(:T2 !B3 A3);
+    use Module qw(:DEFAULT :T2 !B3 A3);
     use Socket qw(!/^[AP]F_/ !SOMAXCONN !SOL_SOCKET);
     use POSIX  qw(/^S_/ acos asin atan /^E/ !/^EXIT/);
 
+You can set C<$Exporter::Verbose=1;> to see how the specifications are
+being processed and what is actually being imported into modules.
+
 =cut
 
 require 5.001;
@@ -110,7 +119,7 @@ sub export {
 		}
 	    }
 	}
-	die "Can't continue with import errors.\n" if $oops;
+	Carp::croak("Can't continue with import errors.\n") if $oops;
     }
     else {
 	@imports = @exports;
diff --git a/lib/ExtUtils/MakeMaker.pm b/lib/ExtUtils/MakeMaker.pm
index fb2dc14af4..0e3d0497f4 100644
--- a/lib/ExtUtils/MakeMaker.pm
+++ b/lib/ExtUtils/MakeMaker.pm
@@ -1,6 +1,6 @@
 package ExtUtils::MakeMaker;
 
-$Version = 4.094; # Last edited 17 Apr 1995 by Andy Dougherty
+$Version = 4.095; # Last edited 17 Apr 1995 by Andy Dougherty
 
 use Config;
 use Carp;
@@ -835,7 +835,7 @@ EOM
 }
 
 
-sub init_dirscan {	# --- File and Directory Lists (.xs .pm etc)
+sub init_dirscan {	# --- File and Directory Lists (.xs .pm .pod etc)
 
     my($name, %dir, %xs, %c, %h, %ignore, %pl_files);
     local(%pm); #the sub in find() has to see this hash
@@ -853,7 +853,7 @@ sub init_dirscan {	# --- File and Directory Lists (.xs .pm etc)
 	    $c{$name} = 1;
 	} elsif ($name =~ /\.h$/){
 	    $h{$name} = 1;
-	} elsif ($name =~ /\.p[ml]$/){
+	} elsif ($name =~ /\.(p[ml]|pod)$/){
 	    $pm{$name} = "\$(INST_LIBDIR)/$name";
 	} elsif ($name =~ /\.PL$/ && $name ne "Makefile.PL") {
 	    ($pl_files{$name} = $name) =~ s/\.PL$// ;
@@ -2336,27 +2336,49 @@ F<E<lt>bailey@HMIVAX.HUMGEN.UPENN.EDUE<gt>>.
 =head1 MODIFICATION HISTORY
 
 v1, August 1994; by Andreas Koenig. Based on Andy Dougherty's Makefile.SH.
+
 v2, September 1994 by Tim Bunce.
+
 v3.0 October  1994 by Tim Bunce.
+
 v3.1 November 11th 1994 by Tim Bunce.
+
 v3.2 November 18th 1994 by Tim Bunce.
+
 v3.3 November 27th 1994 by Andreas Koenig.
+
 v3.4 December  7th 1994 by Andreas Koenig and Tim Bunce.
+
 v3.5 December 15th 1994 by Tim Bunce.
+
 v3.6 December 15th 1994 by Tim Bunce.
+
 v3.7 December 30th 1994 By Tim Bunce
+
 v3.8 January  17th 1995 By Andreas Koenig and Tim Bunce
+
 v3.9 January 19th 1995 By Tim Bunce
+
 v3.10 January 23rd 1995 By Tim Bunce
+
 v3.11 January 24th 1995 By Andreas Koenig
+
 v4.00 January 24th 1995 By Tim Bunce
+
 v4.01 January 25th 1995 By Tim Bunce
+
 v4.02 January 29th 1995 By Andreas Koenig
+
 v4.03 January 30th 1995 By Andreas Koenig
+
 v4.04 Februeary 5th 1995 By Andreas Koenig
+
 v4.05 February 8th 1995 By Andreas Koenig
+
 v4.06 February 10th 1995 By Andreas Koenig
+
 v4.061 February 12th 1995 By Andreas Koenig
+
 v4.08 - 4.085  February 14th-21st 1995 by Andreas Koenig
 
 Introduces EXE_FILES and INST_EXE for installing executable scripts 
@@ -2384,7 +2406,7 @@ Variable LIBPERL_A enables indirect setting of the switches -DEMBED,
 old_extliblist() code deleted, new_extliblist() renamed to extliblist().
 
 Improved algorithm in extliblist, that returns ('','','') if no
-library has been found, even if a -L directory has been found.
+library has been found, even if a C<-L> directory has been found.
 
 Fixed a bug that didn't allow lib/ directory work as documented.
 
@@ -2436,7 +2458,7 @@ v4.091 April 3 1995 by Andy Dougherty
 
 Another attempt to fix writedoc() from Dean Roehrich.
 
-v4.092 April 11 1994 by Andreas Koenig
+v4.092 April 11 1995 by Andreas Koenig
 
 Fixed a docu bug in hint file description. Added printing of a warning
 from eval in the hintfile section if the eval has errors.  Moved
@@ -2456,7 +2478,7 @@ line for the linking of a new static perl.
 
 Minor cosmetics.
 
-v4.093 April 12 1994 by Andy Dougherty
+v4.093 April 12 1995 by Andy Dougherty
 
 Rename distclean target to plain dist.  Insert a dummy distclean
 target that's the same as realclean.  This is more consistent with the
@@ -2468,10 +2490,16 @@ are handled.
 Include Tim's suggestions about $verbose and more careful substitution
 of $(CC) for $Config{'cc'}.
 
-v4.094 April 12 1994 by Andy Dougherty
+v4.094 April 12 1995 by Andy Dougherty
 
 Include Andreas' improvement of $(CC) detection.
 
+v4.095 May 30 1995 by Andy Dougherty
+
+Include installation of .pod and .pm files.
+
+Space out documentation for better printing with pod2man.
+
 =head1 NOTES
 
 MakeMaker development work still to be done:
diff --git a/lib/ExtUtils/xsubpp b/lib/ExtUtils/xsubpp
index 21bbc4edee..3be47e005c 100755
--- a/lib/ExtUtils/xsubpp
+++ b/lib/ExtUtils/xsubpp
@@ -50,12 +50,97 @@ No environment variables are used.
 
 Larry Wall
 
+=head1 MODIFICATION HISTORY
+
+=head2 1.0
+
+I<xsubpp> as released with Perl 5.000
+
+=head2 1.1
+
+I<xsubpp> as released with Perl 5.001
+
+=head2 1.2 
+
+Changes by Paul Marquess <pmarquess@bfsec.bt.co.uk>, 22 May 1995.
+
+=over 5
+
+=item 1.
+
+Added I<xsubpp> version number for the first time. As previous releases
+of I<xsubpp> did not have a formal version number, a numbering scheme
+has been applied retrospectively.
+
+=item 2.
+
+If OUTPUT: is being used to specify output parameters and RETVAL is
+also to be returned, it is now no longer necessary for the user to
+ensure that RETVAL is specified last.
+
+=item 3.
+
+The I<xsubpp> version number, the .xs filename and a time stamp are
+written to the generated .c file as a comment.
+
+=item 4.
+
+When I<xsubpp> is parsing the definition of both the input parameters
+and the OUTPUT parameters, any duplicate definitions will be noted and
+ignored.
+
+=item 5.
+
+I<xsubpp> is slightly more forgiving with extra whitespace.
+
+=back
+
+=head2 1.3 
+
+Changes by Paul Marquess <pmarquess@bfsec.bt.co.uk>, 23 May 1995.
+
+=over 5
+
+=item 1.
+
+More whitespace restrictions have been relaxed. In particular some
+cases where a tab character was used to delimit fields has been
+removed. In these cases any whitespace will now suffice.
+
+The specific places where changes have been made are in the TYPEMAP
+section of a typemap file and the input and OUTPUT: parameter
+declarations sections in a .xs file.
+
+=item 2.
+
+More error checking added.
+
+Before processing each typemap file I<xsubpp> now checks that it is a
+text file. If not an warning will be displayed. In addition, a warning
+will be displayed if it is not possible to open the typemap file.
+
+In the TYPEMAP section of a typemap file, an error will be raised if
+the line does not have 2 columns.
+
+When parsing input parameter declarations check that there is at least
+a type and name pair.
+
+=back
+
+=head2 1.4 
+
+When parsing the OUTPUT arguments check that they are all present in
+the corresponding input argument definitions.
+
 =head1 SEE ALSO
 
 perl(1)
 
 =cut
 
+# Global Constants
+$XSUBPP_version = "1.4" ;
+
 $usage = "Usage: xsubpp [-C++] [-except] [-typemap typemap] file.xs\n";
 
 SWITCH: while ($ARGV[0] =~ s/^-//) {
@@ -75,6 +160,27 @@ if ($pwd =~ /unrecognized command verb/) { $Is_VMS = 1; $pwd = $ENV{DEFAULT} }
 	or ($dir, $filename) = ('.', $ARGV[0]);
 chdir($dir);
 
+sub TrimWhitespace
+{
+    $_[0] =~ s/^\s+|\s+$//go ;
+}
+
+sub TidyType
+{
+    local ($_) = @_ ;
+
+    # rationalise any '*' by joining them into bunches and removing whitespace
+    s#\s*(\*+)\s*#$1#g;
+
+    # change multiple whitespace into a single space
+    s/\s+/ /g ;
+    
+    # trim leading & trailing whitespace
+    TrimWhitespace($_) ;
+
+    $_ ;
+}
+
 $typemap = shift @ARGV;
 foreach $typemap (@tm) {
     die "Can't find $typemap in $pwd\n" unless -r $typemap;
@@ -83,7 +189,12 @@ unshift @tm, qw(../../../../lib/ExtUtils/typemap ../../../lib/ExtUtils/typemap
                 ../../lib/ExtUtils/typemap ../../../typemap ../../typemap
                 ../typemap typemap);
 foreach $typemap (@tm) {
-    open(TYPEMAP, $typemap) || next;
+    next unless -e $typemap ;
+    # skip directories, binary files etc.
+    warn("Warning: ignoring non-text typemap file '$typemap'\n"), next 
+	unless -T $typemap ;
+    open(TYPEMAP, $typemap) 
+	or warn ("Warning: could not open typemap file '$typemap': $!\n"), next;
     $mode = Typemap;
     $current = \$junk;
     while (<TYPEMAP>) {
@@ -93,8 +204,16 @@ foreach $typemap (@tm) {
 	if (/^TYPEMAP\s*$/) { $mode = Typemap, next }
 	if ($mode eq Typemap) {
 	    chop;
-	    ($typename, $kind) = split(/\t+/, $_, 2);
-	    $type_kind{$typename} = $kind if $kind ne '';
+	    my $line = $_ ;
+            TrimWhitespace($_) ;
+	    # skip blank lines and comment lines
+	    next if /^$/ or /^#/ ;
+	    my @words = split (' ') ;
+	    blurt("Error: File '$typemap' Line $. '$line' TYPEMAP entry needs 2 columns\n"), next 
+		unless @words >= 2 ;
+	    my $kind = pop @words ;
+            TrimWhitespace($kind) ;
+	    $type_kind{TidyType("@words")} = $kind ;
 	}
 	elsif ($mode eq Input) {
 	    if (/^\s/) {
@@ -132,7 +251,19 @@ sub Q {
     $text;
 }
 
-open(F, $filename) || die "cannot open $filename\n";
+# Identify the version of xsubpp used
+$TimeStamp = localtime ;
+print <<EOM ;
+/* 
+ * This file was generated automatically by xsubpp version $XSUBPP_version
+ * from $filename on $TimeStamp
+ *
+ */
+ 
+EOM
+ 
+
+open(F, $filename) or die "cannot open $filename: $!\n";
 
 while (<F>) {
     last if ($Module, $foo, $Package, $foo1, $Prefix) =
@@ -196,9 +327,11 @@ while (&fetch_para) {
     undef($class);
     undef($static);
     undef($elipsis);
+    undef($wantRETVAL) ;
+    undef(%arg_list) ;
 
     # extract return type, function name and arguments
-    $ret_type = shift(@line);
+    $ret_type = TidyType(shift(@line));
     if ($ret_type =~ /^BOOT:/) {
         push (@BootCode, @line, "", "") ;
         next ;
@@ -325,11 +458,20 @@ EOF
 		$_ = shift(@line);
 		last if /^\s*NOT_IMPLEMENTED_YET/;
 		last if /^\s*(PPCODE|CODE|OUTPUT|CLEANUP|CASE)\s*:/;
-		($var_type, $var_name, $var_init) =
-		    /\s*([^\t]+)\s*([^\s=]+)\s*(=.*)?/;
-		# Catch common errors. More error checking required here.
-		blurt("Error: no tab in $pname argument declaration '$_'\n")
-			unless (m/\S+\s*\t\s*\S+/);
+
+                TrimWhitespace($_) ;
+                # skip blank lines 
+                next if /^$/ ;
+		my $line = $_ ;
+	  	# check for optional initialisation code
+		my $var_init = $1 if s/\s*(=.*)$// ;
+
+                my @words = split (' ') ;
+                blurt("Error: invalid argument declaration '$line'"), next
+                    unless @words >= 2 ;
+                my $var_name = pop @words ;
+		my $var_type = "@words" ;
+
 		# catch C style argument declaration (this could be made alowable syntax)
 		warn("Warning: ignored semicolon in $pname argument declaration '$_'\n")
 			if ($var_name =~ s/;//g); # eg SV *<tab>name;
@@ -340,6 +482,11 @@ EOF
 			$var_name =~ s/^&//;
 			$var_addr{$var_name} = 1;
 		}
+
+	        # Check for duplicate definitions
+	        blurt ("Error: duplicate definition of argument '$var_name' ignored"), next
+		    if $arg_list{$var_name} ++  ;
+
 		$thisdone |= $var_name eq "THIS";
 		$retvaldone |= $var_name eq "RETVAL";
 		$var_types{$var_name} = $var_type;
@@ -425,29 +572,48 @@ EOF
 				$func_name = $2;
 			}
 			print "$func_name($func_args);\n";
-			&generate_output($ret_type, 0, "RETVAL")
-			    unless $ret_type eq "void";
+			$wantRETVAL = 1 
+	    		    unless $ret_type eq "void";
 		}
 	}
 
 	# do output variables
 	if (/^\s*OUTPUT\s*:/) {
+		my $gotRETVAL ;
+		my %outargs ;
 		while (@line) {
 			$_ = shift(@line);
 			last if /^\s*CLEANUP\s*:/;
-			s/^\s+//;
-			($outarg, $outcode) = split(/\t+/);
+			TrimWhitespace($_) ;
+			next if /^$/ ;
+			my ($outarg, $outcode) = /^(\S+)\s*(.*)/ ;
+			if (!$gotRETVAL and $outarg eq 'RETVAL') {
+			    # deal with RETVAL last
+			    push(@line, $_) ;
+			    $gotRETVAL = 1 ;
+			    undef ($wantRETVAL) ;
+			    next ;
+			}
+			blurt ("Error: duplicate OUTPUT argument '$outarg' ignored"), next
+			    if $outargs{$outarg} ++ ;
+			blurt ("Error: OUTPUT $outarg not an argument"), next
+			    unless defined($args_match{$outarg});
+			blurt("Error: No input definition for OUTPUT argument '$outarg' - ignored"), next
+			    unless defined $var_types{$outarg} ;
 			if ($outcode) {
 			    print "\t$outcode\n";
 			} else {
-				die "$outarg not an argument"
-				    unless defined($args_match{$outarg});
 				$var_num = $args_match{$outarg};
 				&generate_output($var_types{$outarg}, $var_num,
 				    $outarg); 
 			}
 		}
 	}
+
+	# all OUTPUT done, so now push the return value on the stack
+	&generate_output($ret_type, 0, "RETVAL")
+	     if $wantRETVAL ;
+
 	# do cleanup
 	if (/^\s*CLEANUP\s*:/) {
 	    while (@line) {
@@ -533,7 +699,8 @@ sub generate_init {
     local($ntype);
     local($tk);
 
-    blurt("'$type' not in typemap"), return unless defined($type_kind{$type});
+    $type = TidyType($type) ;
+    blurt("Error: '$type' not in typemap"), return unless defined($type_kind{$type});
     ($ntype = $type) =~ s/\s*\*/Ptr/g;
     $subtype = $ntype;
     $subtype =~ s/Ptr$//;
@@ -570,10 +737,11 @@ sub generate_output {
     local($argoff) = $num - 1;
     local($ntype);
 
+    $type = TidyType($type) ;
     if ($type =~ /^array\(([^,]*),(.*)\)/) {
 	    print "\tsv_setpvn($arg, (char *)$var, $2 * sizeof($1)), XFree((char *)$var);\n";
     } else {
-	    blurt("'$type' not in typemap"), return
+	    blurt("Error: '$type' not in typemap"), return
 		unless defined($type_kind{$type});
 	    ($ntype = $type) =~ s/\s*\*/Ptr/g;
 	    $ntype =~ s/\(\)//g;
diff --git a/lib/File/Basename.pm b/lib/File/Basename.pm
index 5e09ae4977..596bff4494 100644
--- a/lib/File/Basename.pm
+++ b/lib/File/Basename.pm
@@ -1,5 +1,116 @@
 package File::Basename;
 
+=head1 NAME
+
+Basename - parse file specifications
+
+fileparse - split a pathname into pieces
+
+basename - extract just the filename from a path
+
+dirname - extract just the directory from a path
+
+=head1 SYNOPSIS
+
+    use File::Basename;
+
+    ($name,$path,$suffix) = fileparse($fullname,@suffixlist)
+    fileparse_set_fstype($os_string);
+    $basename = basename($fullname,@suffixlist);
+    $dirname = dirname($fullname);
+
+    ($name,$path,$suffix) = fileparse("lib/File/Basename.pm","\.pm");
+    fileparse_set_fstype("VMS");
+    $basename = basename("lib/File/Basename.pm",".pm");
+    $dirname = dirname("lib/File/Basename.pm");
+
+=head1 DESCRIPTION
+
+These routines allow you to parse file specifications into useful
+pieces using the syntax of different operating systems.
+
+=over 4
+
+=item fileparse_set_fstype
+
+You select the syntax via the routine fileparse_set_fstype().
+If the argument passed to it contains one of the substrings
+"VMS", "MSDOS", or "MacOS", the file specification syntax of that
+operating system is used in future calls to fileparse(),
+basename(), and dirname().  If it contains none of these
+substrings, UNIX syntax is used.  This pattern matching is
+case-insensitive.  If you've selected VMS syntax, and the file
+specification you pass to one of these routines contains a "/",
+they assume you are using UNIX emulation and apply the UNIX syntax
+rules instead, for that function call only.
+
+If you haven't called fileparse_set_fstype(), the syntax is chosen
+by examining the "osname" entry from the C<Config> package
+according to these rules.
+
+=item fileparse
+
+The fileparse() routine divides a file specification into three
+parts: a leading B<path>, a file B<name>, and a B<suffix>.  The
+B<path> contains everything up to and including the last directory
+separator in the input file specification.  The remainder of the input
+file specification is then divided into B<name> and B<suffix> based on
+the optional patterns you specify in C<@suffixlist>.  Each element of
+this list is interpreted as a regular expression, and is matched
+against the end of B<name>.  If this succeeds, the matching portion of
+B<name> is removed and prepended to B<suffix>.  By proper use of
+C<@suffixlist>, you can remove file types or versions for examination.
+
+You are guaranteed that if you concatenate B<path>, B<name>, and
+B<suffix> together in that order, the result will be identical to the
+input file specification.
+
+=back
+
+=head1 EXAMPLES
+
+Using UNIX file syntax:
+
+    ($base,$path,$type) = fileparse('/virgil/aeneid/draft.book7', 
+				    '\.book\d+');
+
+would yield
+
+    $base eq 'draft'
+    $path eq '/virgil/aeneid',
+    $tail eq '.book7'
+
+Similarly, using VMS syntax:
+
+    ($name,$dir,$type) = fileparse('Doc_Root:[Help]Rhetoric.Rnh',
+				   '\..*');
+
+would yield
+
+    $name eq 'Rhetoric'
+    $dir  eq 'Doc_Root:[Help]'
+    $type eq '.Rnh'
+
+=item C<basename>
+
+The basename() routine returns the first element of the list produced
+by calling fileparse() with the same arguments.  It is provided for
+compatibility with the UNIX shell command basename(1).
+
+=item C<dirname>
+
+The dirname() routine returns the directory portion of the input file
+specification.  When using VMS or MacOS syntax, this is identical to the
+second element of the list produced by calling fileparse() with the same
+input file specification.  When using UNIX or MSDOS syntax, the return
+value conforms to the behavior of the UNIX shell command dirname(1).  This
+is usually the same as the behavior of fileparse(), but differs in some
+cases.  For example, for the input file specification F<lib/>, fileparse()
+considers the directory name to be F<lib/>, while dirname() considers the
+directory name to be F<.>).
+
+=cut
+
 require 5.000;
 use Config;
 require Exporter;
@@ -62,7 +173,7 @@ sub fileparse_set_fstype {
 sub fileparse {
   my($fullname,@suffices) = @_;
   my($fstype) = $Fileparse_fstype;
-  my($dirpath,$tail,$suffix,$idx);
+  my($dirpath,$tail,$suffix);
 
   if ($fstype =~ /^VMS/i) {
     if ($fullname =~ m#/#) { $fstype = '' }  # We're doing Unix emulation
@@ -84,6 +195,7 @@ sub fileparse {
   }
 
   if (@suffices) {
+    $tail = '';
     foreach $suffix (@suffices) {
       if ($basename =~ /($suffix)$/) {
         $tail = $1 . $tail;
diff --git a/lib/File/CheckTree.pm b/lib/File/CheckTree.pm
index a440bda71e..a39308b6c9 100644
--- a/lib/File/CheckTree.pm
+++ b/lib/File/CheckTree.pm
@@ -2,6 +2,45 @@ package File::CheckTree;
 require 5.000;
 require Exporter;
 
+=head1 NAME
+
+validate - run many filetest checks on a tree
+
+=head1 SYNOPSIS
+
+    use File::CheckTree;
+
+    $warnings += validate( q{
+	/vmunix                 -e || die
+	/boot                   -e || die
+	/bin                    cd
+	    csh                 -ex
+	    csh                 !-ug
+	    sh                  -ex
+	    sh                  !-ug
+	/usr                    -d || warn "What happened to $file?\n"
+    });
+
+=head1 DESCRIPTION
+
+The validate() routine takes a single multiline string consisting of
+lines containing a filename plus a file test to try on it.  (The
+file test may also be a "cd", causing subsequent relative filenames
+to be interpreted relative to that directory.)  After the file test
+you may put C<|| die> to make it a fatal error if the file test fails.
+The default is C<|| warn>.  The file test may optionally have a "!' prepended
+to test for the opposite condition.  If you do a cd and then list some
+relative filenames, you may want to indent them slightly for readability.
+If you supply your own die() or warn() message, you can use $file to
+interpolate the filename.
+
+Filetests may be bunched:  "-rwx" tests for all of C<-r>, C<-w>, and C<-x>.
+Only the first failed test of the bunch will produce a warning.
+
+The routine returns the number of warnings issued.
+
+=cut
+
 @ISA = qw(Exporter);
 @EXPORT = qw(validate);
 
diff --git a/lib/File/Find.pm b/lib/File/Find.pm
index c7b0051ce2..ba495a140a 100644
--- a/lib/File/Find.pm
+++ b/lib/File/Find.pm
@@ -5,6 +5,61 @@ use Config;
 use Cwd;
 use File::Basename;
 
+=head1 NAME
+
+find - traverse a file tree
+
+finddepth - traverse a directory structure depth-first
+
+=head1 SYNOPSIS
+
+    use File::Find;
+    find(\&wanted, '/foo','/bar');
+    sub wanted { ... }
+    
+    use File::Find;
+    finddepth(\&wanted, '/foo','/bar');
+    sub wanted { ... }
+
+=head1 DESCRIPTION
+
+The wanted() function does whatever verifications you want.  $dir contains
+the current directory name, and $_ the current filename within that
+directory.  $name contains C<"$dir/$_">.  You are chdir()'d to $dir when
+the function is called.  The function may set $prune to prune the tree.
+
+This library is primarily for the C<find2perl> tool, which when fed, 
+
+    find2perl / -name .nfs\* -mtime +7 \
+	-exec rm -f {} \; -o -fstype nfs -prune
+
+produces something like:
+
+    sub wanted {
+        /^\.nfs.*$/ &&
+        (($dev,$ino,$mode,$nlink,$uid,$gid) = lstat($_)) &&
+        int(-M _) > 7 &&
+        unlink($_)
+        ||
+        ($nlink || (($dev,$ino,$mode,$nlink,$uid,$gid) = lstat($_))) &&
+        $dev < 0 &&
+        ($prune = 1);
+    }
+
+Set the variable $dont_use_nlink if you're using AFS, since AFS cheats.
+
+C<finddepth> is just like C<find>, except that it does a depth-first
+search.
+
+Here's another interesting wanted function.  It will find all symlinks
+that don't resolve:
+
+    sub wanted {
+	-l && !-e && print "bogus link: $name\n";
+    } 
+
+=cut
+
 @ISA = qw(Exporter);
 @EXPORT = qw(find finddepth $name $dir);
 
diff --git a/lib/FileHandle.pm b/lib/FileHandle.pm
index c45f446667..9408717a7c 100644
--- a/lib/FileHandle.pm
+++ b/lib/FileHandle.pm
@@ -2,6 +2,55 @@ package FileHandle;
 
 # Note that some additional FileHandle methods are defined in POSIX.pm.
 
+=head1 NAME 
+
+FileHandle - supply object methods for filehandles
+
+cacheout - keep more files open than the system permits
+
+=head1 SYNOPSIS
+
+    use FileHandle;
+    autoflush STDOUT 1;
+
+    cacheout($path);
+    print $path @data;
+
+=head1 DESCRIPTION
+
+See L<perlvar> for complete descriptions of each of the following supported C<FileHandle> 
+methods:
+
+    print
+    autoflush
+    output_field_separator
+    output_record_separator
+    input_record_separator
+    input_line_number
+    format_page_number
+    format_lines_per_page
+    format_lines_left
+    format_name
+    format_top_name
+    format_line_break_characters
+    format_formfeed
+
+The cacheout() function will make sure that there's a filehandle
+open for writing available as the pathname you give it.  It automatically
+closes and re-opens files if you exceed your system file descriptor maximum.
+
+=head1 BUGS
+
+F<sys/param.h> lies with its C<NOFILE> define on some systems,
+so you may have to set $cacheout::maxopen yourself.
+
+Due to backwards compatibility, all filehandles resemble objects
+of class C<FileHandle>, or actually classes derived from that class.
+They actually aren't.  Which means you can't derive your own 
+class from C<FileHandle> and inherit those methods.
+
+=cut
+
 require 5.000;
 use English;
 use Exporter;
diff --git a/lib/Getopt/Long.pm b/lib/Getopt/Long.pm
index 48cda7e12a..43e1e58e59 100644
--- a/lib/Getopt/Long.pm
+++ b/lib/Getopt/Long.pm
@@ -5,6 +5,144 @@ require Exporter;
 @ISA = qw(Exporter);
 @EXPORT = qw(GetOptions);
 
+=head1 NAME
+
+GetOptions - extended getopt processing
+
+=head1 SYNOPSIS
+
+    use Getopt::Long;
+    $result = GetOptions (...option-descriptions...);
+
+=head1 DESCRIPTION
+
+The Getopt::Long module implements an extended getopt function called
+GetOptions(). This function adheres to the new syntax (long option names,
+no bundling).  It tries to implement the better functionality of
+traditional, GNU and POSIX getopt() functions.
+
+Each description should designate a valid Perl identifier, optionally
+followed by an argument specifier.
+
+Values for argument specifiers are:
+
+  <none>   option does not take an argument
+  !        option does not take an argument and may be negated
+  =s :s    option takes a mandatory (=) or optional (:) string argument
+  =i :i    option takes a mandatory (=) or optional (:) integer argument
+  =f :f    option takes a mandatory (=) or optional (:) real number argument
+
+If option "name" is set, it will cause the Perl variable $opt_name to
+be set to the specified value. The calling program can use this
+variable to detect whether the option has been set. Options that do
+not take an argument will be set to 1 (one).
+
+Options that take an optional argument will be defined, but set to ''
+if no actual argument has been supplied.
+
+If an "@" sign is appended to the argument specifier, the option is
+treated as an array.  Value(s) are not set, but pushed into array
+@opt_name.
+
+Options that do not take a value may have an "!" argument specifier to
+indicate that they may be negated. E.g. "foo!" will allow B<-foo> (which
+sets $opt_foo to 1) and B<-nofoo> (which will set $opt_foo to 0).
+
+The option name may actually be a list of option names, separated by
+'|'s, e.g. B<"foo|bar|blech=s". In this example, options 'bar' and
+'blech' will set $opt_foo instead.
+
+Option names may be abbreviated to uniqueness, depending on
+configuration variable $autoabbrev.
+
+Dashes in option names are allowed (e.g. pcc-struct-return) and will
+be translated to underscores in the corresponding Perl variable (e.g.
+$opt_pcc_struct_return).  Note that a lone dash "-" is considered an
+option, corresponding Perl identifier is $opt_ .
+
+A double dash "--" signals end of the options list.
+
+If the first option of the list consists of non-alphanumeric
+characters only, it is interpreted as a generic option starter.
+Everything starting with one of the characters from the starter will
+be considered an option.
+
+The default values for the option starters are "-" (traditional), "--"
+(POSIX) and "+" (GNU, being phased out).
+
+Options that start with "--" may have an argument appended, separated
+with an "=", e.g. "--foo=bar".
+
+If configuration variable $getopt_compat is set to a non-zero value,
+options that start with "+" may also include their arguments,
+e.g. "+foo=bar".
+
+A return status of 0 (false) indicates that the function detected
+one or more errors.
+
+=head1 EXAMPLES
+
+If option "one:i" (i.e. takes an optional integer argument), then
+the following situations are handled:
+
+   -one -two		-> $opt_one = '', -two is next option
+   -one -2		-> $opt_one = -2
+
+Also, assume "foo=s" and "bar:s" :
+
+   -bar -xxx		-> $opt_bar = '', '-xxx' is next option
+   -foo -bar		-> $opt_foo = '-bar'
+   -foo --		-> $opt_foo = '--'
+
+In GNU or POSIX format, option names and values can be combined:
+
+   +foo=blech		-> $opt_foo = 'blech'
+   --bar=		-> $opt_bar = ''
+   --bar=--		-> $opt_bar = '--'
+
+=over 12
+
+=item $autoabbrev      
+
+Allow option names to be abbreviated to uniqueness.
+Default is 1 unless environment variable
+POSIXLY_CORRECT has been set.
+
+=item $getopt_compat   
+
+Allow '+' to start options.
+Default is 1 unless environment variable
+POSIXLY_CORRECT has been set.
+
+=item $option_start    
+
+Regexp with option starters.
+Default is (--|-) if environment variable
+POSIXLY_CORRECT has been set, (--|-|\+) otherwise.
+
+=item $order           
+
+Whether non-options are allowed to be mixed with
+options.
+Default is $REQUIRE_ORDER if environment variable
+POSIXLY_CORRECT has been set, $PERMUTE otherwise.
+
+=item $ignorecase      
+
+Ignore case when matching options. Default is 1.
+
+=item $debug           
+
+Enable debugging output. Default is 0.
+
+=back
+
+=head1 NOTE
+
+Does not yet use the Exporter--or even packages!!
+Thus, it's not a real module.
+
+=cut
 
 # newgetopt.pl -- new options parsing
 
@@ -316,7 +454,7 @@ sub GetOptions {
 
 	# Double dash is option list terminator.
 	if ( $opt eq $argend ) {
-	    unshift (@ret, @ARGV) if $order == $PERMUTE;
+	    unshift (@ARGV, @ret) if $order == $PERMUTE;
 	    return ($error == 0);
 	}
 	elsif ( $opt =~ /^$genprefix/ ) {
diff --git a/lib/Getopt/Std.pm b/lib/Getopt/Std.pm
index e1de3b531f..4117ca7f8b 100644
--- a/lib/Getopt/Std.pm
+++ b/lib/Getopt/Std.pm
@@ -2,6 +2,30 @@ package Getopt::Std;
 require 5.000;
 require Exporter;
 
+=head1 NAME
+
+getopt - Process single-character switches with switch clustering
+
+getopts - Process single-character switches with switch clustering
+
+=head1 SYNOPSIS
+
+    use Getopt::Std;
+    getopt('oDI');  # -o, -D & -I take arg.  Sets opt_* as a side effect.
+    getopts('oif:');  # -o & -i are boolean flags, -f takes an argument
+		      # Sets opt_* as a side effect.
+
+=head1 DESCRIPTION
+
+The getopt() functions processes single-character switches with switch
+clustering.  Pass one argument which is a string containing all switches
+that take an argument.  For each switch found, sets $opt_x (where x is the
+switch name) to the value of the argument, or 1 if no argument.  Switches
+which take an argument don't care whether there is a space between the
+switch and the argument.
+
+=cut
+
 @ISA = qw(Exporter);
 @EXPORT = qw(getopt getopts);
 
@@ -64,7 +88,7 @@ sub getopts {
 	($first,$rest) = ($1,$2);
 	$pos = index($argumentative,$first);
 	if($pos >= 0) {
-	    if($args[$pos+1] eq ':') {
+	    if(defined($args[$pos+1]) and ($args[$pos+1] eq ':')) {
 		shift(@ARGV);
 		if($rest eq '') {
 		    ++$errs unless @ARGV;
diff --git a/lib/I18N/Collate.pm b/lib/I18N/Collate.pm
index 52c78abe83..35c8025367 100644
--- a/lib/I18N/Collate.pm
+++ b/lib/I18N/Collate.pm
@@ -1,5 +1,39 @@
 package I18N::Collate;
 
+=head1 NAME
+
+Collate - compare 8-bit scalar data according to the current locale
+
+=head1 SYNOPSIS
+
+    use Collate;
+    setlocale(LC_COLLATE, 'locale-of-your-choice'); 
+    $s1 = new Collate "scalar_data_1";
+    $s2 = new Collate "scalar_data_2";
+
+=head1 DESCRIPTION
+
+This module provides you with objects that will collate 
+according to your national character set, providing the 
+POSIX setlocale() function should be supported on your system.
+
+You can compare $s1 and $s2 above with
+
+    $s1 le $s2
+
+to extract the data itself, you'll need a dereference: $$s1
+
+This uses POSIX::setlocale The basic collation conversion is done by
+strxfrm() which terminates at NUL characters being a decent C routine.
+collate_xfrm() handles embedded NUL characters gracefully.  Due to C<cmp>
+and overload magic, C<lt>, C<le>, C<eq>, C<ge>, and C<gt> work also.  The
+available locales depend on your operating system; try whether C<locale
+-a> shows them or the more direct approach C<ls /usr/lib/nls/loc> or C<ls
+/usr/lib/nls>.  The locale names are probably something like
+"xx_XX.(ISO)?8859-N".
+
+=cut
+
 # Collate.pm
 #
 # Author:	Jarkko Hietaniemi <Jarkko.Hietaniemi@hut.fi>
diff --git a/lib/IPC/Open2.pm b/lib/IPC/Open2.pm
index c59c7d6897..71f89f35c2 100644
--- a/lib/IPC/Open2.pm
+++ b/lib/IPC/Open2.pm
@@ -3,6 +3,51 @@ require 5.000;
 require Exporter;
 use Carp;
 
+=head1 NAME
+
+IPC::Open2, open2 - open a process for both reading and writing
+
+=head1 SYNOPSIS
+
+    use IPC::Open2;
+    $pid = open2('rdr', 'wtr', 'some cmd and args');
+      # or
+    $pid = open2('rdr', 'wtr', 'some', 'cmd', 'and', 'args');
+
+=head1 DESCRIPTION
+
+The open2() function spawns the given $cmd and connects $rdr for
+reading and $wtr for writing.  It's what you think should work 
+when you try
+
+    open(HANDLE, "|cmd args");
+
+open2() returns the process ID of the child process.  It doesn't return on
+failure: it just raises an exception matching C</^open2:/>.
+
+=head1 WARNING 
+
+It will not create these file handles for you.  You have to do this yourself.
+So don't pass it empty variables expecting them to get filled in for you.
+
+Additionally, this is very dangerous as you may block forever.
+It assumes it's going to talk to something like B<bc>, both writing to
+it and reading from it.  This is presumably safe because you "know"
+that commands like B<bc> will read a line at a time and output a line at
+a time.  Programs like B<sort> that read their entire input stream first,
+however, are quite apt to cause deadlock.  
+
+The big problem with this approach is that if you don't have control 
+over source code being run in the the child process, you can't control what it does 
+with pipe buffering.  Thus you can't just open a pipe to "cat -v" and continually
+read and write a line from it.
+
+=head1 SEE ALSO
+
+See L<open3> for an alternative that handles STDERR as well.
+
+=cut
+
 @ISA = qw(Exporter);
 @EXPORT = qw(open2);
 
diff --git a/lib/IPC/Open3.pm b/lib/IPC/Open3.pm
index 3426f19111..8d324ccb62 100644
--- a/lib/IPC/Open3.pm
+++ b/lib/IPC/Open3.pm
@@ -3,6 +3,31 @@ require 5.000;
 require Exporter;
 use Carp;
 
+=head1 NAME
+
+IPC::Open3, open3 - open a process for reading, writing, and error handling
+
+=head1 SYNOPSIS
+
+    $pid = open3('WTRFH', 'RDRFH', 'ERRFH' 
+		    'some cmd and args', 'optarg', ...);
+
+=head1 DESCRIPTION
+
+Extremely similar to open2(), open3() spawns the given $cmd and
+connects RDRFH for reading, WTRFH for writing, and ERRFH for errors.  If
+ERRFH is '', or the same as RDRFH, then STDOUT and STDERR of the child are
+on the same file handle.
+
+If WTRFH begins with ">&", then WTRFH will be closed in the parent, and
+the child will read from it directly.  if RDRFH or ERRFH begins with
+">&", then the child will send output directly to that file handle.  In both
+cases, there will be a dup(2) instead of a pipe(2) made.
+
+All caveats from open2() continue to apply.  See L<open2> for details.
+
+=cut
+
 @ISA = qw(Exporter);
 @EXPORT = qw(open3);
 
diff --git a/lib/Net/Ping.pm b/lib/Net/Ping.pm
index 2528f55255..cfc8f9f6a1 100644
--- a/lib/Net/Ping.pm
+++ b/lib/Net/Ping.pm
@@ -1,5 +1,44 @@
 package Net::Ping;
 
+=head1 NAME
+
+Net::Ping, pingecho - check a host for upness
+
+=head1 SYNOPSIS
+
+    use Net::Ping;
+    print "'jimmy' is alive and kicking\n" if pingecho('jimmy', 10) ;
+
+=head1 DESCRIPTION
+
+This module contains routines to test for the reachability of remote hosts.
+Currently the only routine implemented is pingecho(). 
+
+pingecho() uses a TCP echo (I<not> an ICMP one) to determine if the
+remote host is reachable. This is usually adequate to tell that a remote
+host is available to rsh(1), ftp(1), or telnet(1) onto.
+
+=head2 Parameters
+
+=over 5
+
+=item hostname
+
+The remote host to check, specified either as a hostname or as an IP address.
+
+=item timeout
+
+The timeout in seconds. If not specified it will default to 5 seconds.
+
+=back
+
+=head1 WARNING
+
+pingecho() uses alarm to implement the timeout, so don't set another alarm
+while you are using it.
+
+=cut
+
 # Authors: karrer@bernina.ethz.ch (Andreas Karrer)
 #          pmarquess@bfsec.bt.co.uk (Paul Marquess)
 
diff --git a/lib/Term/Complete.pm b/lib/Term/Complete.pm
index 10b12a2b5c..97c71fe43f 100644
--- a/lib/Term/Complete.pm
+++ b/lib/Term/Complete.pm
@@ -37,7 +37,7 @@ CONFIG: {
     $erase2 =   "\010";
 }
 
-sub complete {
+sub Complete {
     $prompt = shift;
     if (ref $_[0] || $_[0] =~ /^\*/) {
 	@cmp_lst = sort @{$_[0]};
diff --git a/lib/Text/Abbrev.pm b/lib/Text/Abbrev.pm
index 77370d37c3..d12dfb36a6 100644
--- a/lib/Text/Abbrev.pm
+++ b/lib/Text/Abbrev.pm
@@ -2,6 +2,28 @@ package Text::Abbrev;
 require 5.000;
 require Exporter;
 
+=head1 NAME
+
+abbrev - create an abbreviation table from a list
+
+=head1 SYNOPSIS
+
+    use Abbrev;
+    abbrev *HASH, LIST
+
+
+=head1 DESCRIPTION
+
+Stores all unambiguous truncations of each element of LIST
+as keys key in the associative array indicated by C<*hash>.
+The values are the original list elements.
+
+=head1 EXAMPLE
+
+    abbrev(*hash,qw("list edit send abort gripe"));
+
+=cut
+
 @ISA = qw(Exporter);
 @EXPORT = qw(abbrev);
 
diff --git a/lib/Text/Tabs.pm b/lib/Text/Tabs.pm
index c90d1aa672..fa866988cf 100644
--- a/lib/Text/Tabs.pm
+++ b/lib/Text/Tabs.pm
@@ -2,10 +2,10 @@
 # expand and unexpand tabs as per the unix expand and 
 # unexpand programs.
 #
-# expand and unexpand operate on arrays of lines.  Do not
-# feed strings that contain newlines to them.
+# expand and unexpand operate on arrays of lines.  
 #
 # David Muir Sharnoff <muir@idiom.com>
+# Version: 4/19/95
 # 
 
 package Text::Tabs;
@@ -19,29 +19,45 @@ $tabstop = 8;
 
 sub expand
 {
-	my @l = @_;
-	for $_ (@l) {
-		1 while s/^([^\t]*)(\t+)/
-			$1 . (" " x 
-				($tabstop * length($2)
-				- (length($1) % $tabstop)))
-			/e;
+	my (@l) = @_;
+	my $l, @k;
+	my $nl;
+	for $l (@l) {
+		$nl = $/ if chomp($l);
+		@k = split($/,$l);
+		for $_ (@k) {
+			1 while s/^([^\t]*)(\t+)/
+				$1 . (" " x 
+					($tabstop * length($2)
+					- (length($1) % $tabstop)))
+				/e;
+		}
+		$l = join("\n",@k).$nl;
 	}
-	return @l;
+	return @l if $#l > 0;
+	return $l[0];
 }
 
 sub unexpand
 {
-	my @l = &expand(@_);
+	my (@l) = &expand(@_);
 	my @e;
-	for $x (@l) {
-		@e = split(/(.{$tabstop})/,$x);
-		for $_ (@e) {
-			s/  +$/\t/;
+	my $k, @k;
+	my $nl;
+	for $k (@l) {
+		$nl = $/ if chomp($k);
+		@k = split($/,$k);
+		for $x (@k) {
+			@e = split(/(.{$tabstop})/,$x);
+			for $_ (@e) {
+				s/  +$/\t/;
+			}
+			$x = join('',@e);
 		}
-		$x = join('',@e);
+		$k = join("\n",@k).$nl;
 	}
-	return @l;
+	return @l if $#l > 0;
+	return $l[0];
 }
 
 1;
diff --git a/lib/integer.pm b/lib/integer.pm
index 74039bb962..a88ce6a77c 100644
--- a/lib/integer.pm
+++ b/lib/integer.pm
@@ -1,5 +1,26 @@
 package integer;
 
+=head1 NAME
+
+integer - Perl pragma to compute arithmetic in integer instead of double
+
+=head1 SYNOPSIS
+
+    use integer;
+    $x = 10/3;
+    # $x is now 3, not 3.33333333333333333
+
+=head1 DESCRIPTION
+
+This tells the compiler that it's okay to use integer operations
+from here to the end of the enclosing BLOCK.  On many machines, 
+this doesn't matter a great deal for most computations, but on those 
+without floating point hardware, it can make a big difference.
+
+See L<perlmod/Pragmatic Modules>.
+
+=cut
+
 sub import {
     $^H |= 1;
 }
diff --git a/lib/less.pm b/lib/less.pm
index a95484ff76..5e055f3920 100644
--- a/lib/less.pm
+++ b/lib/less.pm
@@ -1,2 +1,19 @@
 package less;
+
+=head1 NAME
+
+less - Perl pragma to request less of something from the compiler
+
+=head1 DESCRIPTION
+
+Currently unimplemented, this may someday be a compiler directive
+to make certain trade-offs, such as perhaps
+
+    use less 'memory';
+    use less 'CPU';
+    use less 'fat';
+
+
+=cut
+
 1;
diff --git a/lib/sigtrap.pm b/lib/sigtrap.pm
index 72b9cb6044..dd4df906fa 100644
--- a/lib/sigtrap.pm
+++ b/lib/sigtrap.pm
@@ -1,5 +1,27 @@
 package sigtrap;
 
+=head1 NAME
+
+sigtrap - Perl pragma to enable stack backtrace on unexpected signals
+
+=head1 SYNOPSIS
+
+    use sigtrap;
+    use sigtrap qw(BUS SEGV PIPE SYS ABRT TRAP);
+
+=head1 DESCRIPTION
+
+The C<sigtrap> pragma initializes some default signal handlers that print
+a stack dump of your Perl program, then sends itself a SIGABRT.  This
+provides a nice starting point if something horrible goes wrong.
+
+By default, handlers are installed for the ABRT, BUS, EMT, FPE, ILL, PIPE,
+QUIT, SEGV, SYS, TERM, and TRAP signals.
+
+See L<perlmod/Pragmatic Modules>.
+
+=cut
+
 require Carp;
 
 sub import {
diff --git a/lib/strict.pm b/lib/strict.pm
index adaf47c720..d35c6c105c 100644
--- a/lib/strict.pm
+++ b/lib/strict.pm
@@ -1,5 +1,73 @@
 package strict;
 
+=head1 NAME
+
+strict - Perl pragma to restrict unsafe constructs
+
+=head1 SYNOPSIS
+
+    use strict;
+
+    use strict "vars";
+    use strict "refs";
+    use strict "subs";
+
+    use strict;
+    no strict "vars";
+
+=head1 DESCRIPTION
+
+If no import list is supplied, all possible restrictions are assumed.
+(This is the safest mode to operate in, but is sometimes too strict for
+casual programming.)  Currently, there are three possible things to be
+strict about:  "subs", "vars", and "refs".
+
+=over 6
+
+=item C<strict refs>
+
+This generates a runtime error if you 
+use symbolic references (see L<perlref>).
+
+    use strict 'refs';
+    $ref = \$foo;
+    print $$ref;	# ok
+    $ref = "foo";
+    print $$ref;	# runtime error; normally ok
+
+=item C<strict vars>
+
+This generates a compile-time error if you access a variable that wasn't
+localized via C<my()> or wasn't fully qualified.  Because this is to avoid
+variable suicide problems and subtle dynamic scoping issues, a merely
+local() variable isn't good enough.  See L<perlfunc/my> and
+L<perlfunc/local>.
+
+    use strict 'vars';
+    $X::foo = 1;	 # ok, fully qualified
+    my $foo = 10;	 # ok, my() var
+    local $foo = 9;	 # blows up
+
+The local() generated a compile-time error because you just touched a global
+name without fully qualifying it.
+
+=item C<strict subs>
+
+This disables the poetry optimization,
+generating a compile-time error if you 
+try to use a bareword identifier that's not a subroutine.
+
+    use strict 'subs';
+    $SIG{PIPE} = Plumber;   	# blows up
+    $SIG{"PIPE"} = "Plumber"; 	# just fine
+
+=back
+
+See L<perlmod/Pragmatic Modules>.
+
+
+=cut
+
 sub bits {
     my $bits = 0;
     foreach $sememe (@_) {
diff --git a/lib/subs.pm b/lib/subs.pm
index 8b5835770f..0dbbaddd11 100644
--- a/lib/subs.pm
+++ b/lib/subs.pm
@@ -1,5 +1,23 @@
 package subs;
 
+=head1 NAME
+
+subs - Perl pragma to predeclare sub names
+
+=head1 SYNOPSIS
+
+    use subs qw(frob);
+    frob 3..10;
+
+=head1 DESCRIPTION
+
+This will predeclare all the subroutine whose names are 
+in the list, allowing you to use them without parentheses
+even before they're declared.
+
+See L<perlmod/Pragmatic Modules> and L<strict/subs>.
+
+=cut
 require 5.000;
 
 $ExportLevel = 0;