Pod typos, pod2man bugs, and miscellaneous installation comments

Here is a patch for various typos and other defects in the Perl
5.003_05 pods, including the pods embedded in library modules.

configpm

@@ -196,7 +196,7 @@ Shell variables from the F<config.sh> file (written by Configure) are
 stored in the readonly-variable C<%Config>, indexed by their names.
 
 Values stored in config.sh as 'undef' are returned as undefined
-values.  The perl C<exists> function can be used to check is a
+values.  The perl C<exists> function can be used to check if a
 named variable exists.
 
 =over 4

ext/DynaLoader/DynaLoader.pm

@@ -273,7 +273,7 @@ sub dl_expandspec {
 
 DynaLoader - Dynamically load C libraries into Perl code
 
-dl_error(), dl_findfile(), dl_expandspec(), dl_load_file(), dl_find_symbol(), dl_undef_symbols(), dl_install_xsub(), boostrap() - routines used by DynaLoader modules
+dl_error(), dl_findfile(), dl_expandspec(), dl_load_file(), dl_find_symbol(), dl_undef_symbols(), dl_install_xsub(), bootstrap() - routines used by DynaLoader modules
 
 =head1 SYNOPSIS
 
@@ -523,7 +523,7 @@ the function if required by die(), caller() or the debugger.  If
 $filename is not defined then "DynaLoader" will be used.
 
 
-=item boostrap()
+=item bootstrap()
 
 Syntax:
 

ext/FileHandle/FileHandle.pm

@@ -60,7 +60,7 @@ parameters, the first parameter is a filename that may include
 whitespace or other special characters, and the second parameter is
 the open mode, optionally followed by a file permission value.
 
-If C<FileHandle::open> receives a Perl mode string (">", "+<", etc.)
+If C<FileHandle::open> receives a Perl mode string ("E<gt>", "+E<lt>", etc.)
 or a POSIX fopen() mode string ("w", "r+", etc.), it uses the basic
 Perl C<open> operator.
 
@@ -122,23 +122,23 @@ Furthermore, for doing normal I/O you might need these:
 
 =over 
 
-=item $fh->print
+=item $fh-E<gt>print
 
 See L<perlfunc/print>.
 
-=item $fh->printf
+=item $fh-E<gt>printf
 
 See L<perlfunc/printf>.
 
-=item $fh->getline
+=item $fh-E<gt>getline
 
-This works like <$fh> described in L<perlop/"I/O Operators">
+This works like E<lt>$fhE<gt> described in L<perlop/"I/O Operators">
 except that it's more readable and can be safely called in an
 array context but still returns just one line.
 
-=item $fh->getlines
+=item $fh-E<gt>getlines
 
-This works like <$fh> when called in an array context to
+This works like E<lt>$fhE<gt> when called in an array context to
 read all the remaining lines in a file, except that it's more readable.
 It will also croak() if accidentally called in a scalar context.
 

ext/Opcode/Safe.pm

@@ -287,8 +287,8 @@ compilation to fail with an error. The code will not be executed.
 The default operator mask for a newly created compartment is
 the ':default' optag.
 
-It is important that you read the L<Opcode(3)> module documentation
-for more information. Especially for details definitions of opnames,
+It is important that you read the Opcode(3) module documentation
+for more information, especially for detailed definitions of opnames,
 optags and opsets.
 
 Since it is only at the compilation stage that the operator mask
@@ -454,7 +454,7 @@ problem.
 
 Consider a function foo() in package pkg compiled outside a compartment
 but shared with it. Assume the compartment has a root package called
-'Root'. If foo() contains an eval statement like eval '$baz = 1' then,
+'Root'. If foo() contains an eval statement like eval '$foo = 1' then,
 normally, $pkg::foo will be set to 1.  If foo() is called from the
 compartment (by whatever means) then instead of setting $pkg::foo, the
 eval will actually set $Root::pkg::foo.
@@ -549,7 +549,7 @@ Originally designed and implemented by Malcolm Beattie,
 mbeattie@sable.ox.ac.uk.
 
 Reworked to use the Opcode module and other changes added by Tim Bunce
-<Tim.Bunce@ig.co.uk>.
+E<lt>F<Tim.Bunce@ig.co.uk>E<gt>.
 
 =cut
 

ext/Socket/Socket.pm

@@ -115,10 +115,10 @@ Will croak if the structure does not have AF_INET in the right place.
 =item sockaddr_un SOCKADDR_UN
 
 In an array context, unpacks its SOCKADDR_UN argument and returns an array
-consisting of (PATHNAME).  In a scalar context, packs its PATHANE
+consisting of (PATHNAME).  In a scalar context, packs its PATHNAME
 arguments as a SOCKADDR_UN and returns it.  If this is confusing, use
 pack_sockaddr_un() and unpack_sockaddr_un() explicitly.
-These are only supported if your system has <sys/un.h>.
+These are only supported if your system has E<lt>F<sys/un.h>E<gt>.
 
 =item pack_sockaddr_un PATH
 

installman

@@ -56,37 +56,66 @@ runpod2man('pod', $man1dir, $man1ext);
 # Install the pods for library modules.
 runpod2man('lib', $man3dir, $man3ext);
 
+# Install the pods embedded in the installed scripts
+runpod2man('utils', $man1dir, $man1ext, 'c2ph');
+runpod2man('utils', $man1dir, $man1ext, 'h2ph');
+runpod2man('utils', $man1dir, $man1ext, 'h2xs');
+runpod2man('utils', $man1dir, $man1ext, 'perldoc');
+runpod2man('utils', $man1dir, $man1ext, 'pl2pm');
+runpod2man('x2p', $man1dir, $man1ext, 's2p');
+runpod2man('x2p', $man1dir, $man1ext, 'a2p.pod');
+runpod2man('pod', $man1dir, $man1ext, 'pod2man');
+
+# It would probably be better to have this page linked
+# to the c2ph man page.  Or, this one could say ".so man1/c2ph.1",
+# but then it would have to pay attention to $man1dir and $man1ext.
+runpod2man('utils', $man1dir, $man1ext, 'pstruct'); 
+
+runpod2man('lib/ExtUtils', $man1dir, $man1ext, 'xsubpp');
+
 sub runpod2man {
-    my($poddir, $mandir, $manext) = @_;
+    # $script is script name if we are installing a manpage embedded 
+    # in a script, undef otherwise
+    my($poddir, $mandir, $manext, $script) = @_;
+
+    my($downdir); # can't just use .. when installing xsubpp manpage
+
+    $downdir = $poddir;
+    $downdir =~ s:[^/]+:..:g;
     my($builddir) = Cwd::getcwd();
 
     if ($mandir eq ' ' or $mandir eq '') {
-	print STDERR "Skipping installation of $poddir man pages.\n";
+	print STDERR "Skipping installation of ",
+	    ($script ? "$poddir/$script man page" : "$poddir man pages"), ".\n";
 	return;
     }
 
-    chdir $poddir || die "Unable to cd to $poddir directory!\n$!\n";
     print STDERR "chdir $poddir\n";
+    chdir $poddir || die "Unable to cd to $poddir directory!\n$!\n";
 
     # We insist on using the current version of pod2man in case there
     # are enhancements or changes from previous installed versions.
     # The error message doesn't include the '..' because the user
     # won't be aware that we've chdir to $poddir.
-    -r  "../pod/pod2man" || die "Executable pod/pod2man not found.\n";
+    -r  "$downdir/pod/pod2man" || die "Executable pod/pod2man not found.\n";
 
     # We want to be sure to use the current perl.  We can't rely on
     # the installed perl because it might not be actually installed
     # yet. (The user may have set the $install* Configure variables 
     # to point to some temporary home, from which the executable gets
     # installed by occult means.)
-    $pod2man = "../perl -I ../lib ../pod/pod2man --section=$manext --official";
+    $pod2man = "$downdir/perl -I $downdir/lib $downdir/pod/pod2man --section=$manext --official";
 
     mkpath($mandir, 1, 0777) unless $notify;  # In File::Path
     # Make a list of all the .pm and .pod files in the directory.  We will
     # always run pod2man from the lib directory and feed it the full pathname
     # of the pod.  This might be useful for pod2man someday.
-    @modpods = ();
-    find(\&lsmodpods, '.');
+    if ($script) {
+	@modpods = ($script);
+    } else {
+	@modpods = ();
+	find(\&lsmodpods, '.');
+    }
     foreach $mod (@modpods) {
 	$manpage = $mod;
 	my $tmp;

installperl

@@ -22,15 +22,11 @@ while (@ARGV) {
 
 umask 022;
 
-@scripts = qw(	utils/c2ph utils/h2ph utils/h2xs utils/pstruct
-		utils/perlbug utils/perldoc
+@scripts = qw(	utils/c2ph utils/h2ph utils/h2xs
+		utils/perlbug utils/perldoc utils/pl2pm
 		x2p/s2p x2p/find2perl
 		pod/pod2man pod/pod2html pod/pod2latex pod/pod2text);
 
-# pod documentation now handled by separate installman script.
-# These two are archaic leftovers.
-@manpages = qw(x2p/a2p.man x2p/s2p.man);
-
 @pods = (<pod/*.pod>);
 
 $ver = $];
@@ -120,37 +116,18 @@ for (@scripts) {
     s#.*/##; &chmod(0755, "$installscript/$_");
 }
 
+# pstruct should be a link to c2ph
+
+&safe_unlink("$installscript/pstruct");
+&link("$installscript/c2ph","$installscript/pstruct");
+
 # Install pod pages.  Where? I guess in $installprivlib/pod.
 mkpath("${installprivlib}/pod", 1, 0777);
 foreach $file (@pods) {
     # $file is a name like  pod/perl.pod
     cp_if_diff($file, "${installprivlib}/${file}");
 }
 
-# Install old man pages.
-
-if ($installman1dir ne '') {
-    mkpath($installman1dir, 1, 0777);
-
-    if (! &samepath($installman1dir, '.')) {
-	for (@manpages) {
-	    ($new = $_) =~ s/man$/$man1ext/;
-	    $new =~ s#.*/##;
-	    print STDERR "  Installing $installman1dir/$new\n";
-	    next if $nonono;
-	    open(MI,$_) || warn "Can't open $_: $!\n";
-	    open(MO,">$installman1dir/$new") || 
-		    warn "Can't install $installman1dir/$new: $!\n";
-	    print MO ".ds RP Release $release Patchlevel $patchlevel\n";
-	    while (<MI>) {
-		print MO;
-	    }
-	    close MI;
-	    close MO;
-	}
-    }
-}
-
 # Install library files.
 
 $do_installarchlib = $do_installprivlib = 0;

lib/Cwd.pm

@@ -39,7 +39,7 @@ the trailing line terminator). It is recommended that cwd (or another
 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>.) Note that it will only be
-kept up to date it all packages which use chdir import it from Cwd.
+kept up to date if all packages which use chdir import it from Cwd.
 
 =cut
 

lib/Devel/SelfStubber.pm

@@ -118,7 +118,7 @@ So, for classes and subclasses to have inheritance correctly
 work with autoloading, you need to ensure stubs are loaded.
 
 The SelfLoader can load stubs automatically at module initialization
-with the statement 'SelfLoader->load_stubs()';, but you may wish to
+with the statement 'SelfLoader-E<gt>load_stubs()';, but you may wish to
 avoid having the stub loading overhead associated with your
 initialization (though note that the SelfLoader::load_stubs method
 will be called sooner or later - at latest when the first sub

lib/Env.pm

@@ -39,7 +39,7 @@ the environment, assign it the undefined value
 
 =head1 AUTHOR
 
-Chip Salzenberg <chip@fin.uucp>
+Chip Salzenberg E<lt>F<chip@fin.uucp>E<gt>
 
 =cut
 

lib/Exporter.pm

@@ -264,7 +264,7 @@ try to use @EXPORT_OK in preference to @EXPORT and avoid short or
 common symbol names to reduce the risk of name clashes.
 
 Generally anything not exported is still accessible from outside the
-module using the ModuleName::item_name (or $blessed_ref->method)
+module using the ModuleName::item_name (or $blessed_ref-E<gt>method)
 syntax.  By convention you can use a leading underscore on names to
 informally indicate that they are 'internal' and not for public use.
 
@@ -328,7 +328,7 @@ into modules.
 =head2 Module Version Checking
 
 The Exporter module will convert an attempt to import a number from a
-module into a call to $module_name->require_version($value). This can
+module into a call to $module_name-E<gt>require_version($value). This can
 be used to validate that the version of the module being used is
 greater than or equal to the required version.
 

lib/ExtUtils/Install.pm

@@ -314,8 +314,8 @@ be copied preserving timestamps and permissions.
 
 There are two keys with a special meaning in the hash: "read" and
 "write". After the copying is done, install will write the list of
-target files to the file named by $hashref->{write}. If there is
-another file named by $hashref->{read}, the contents of this file will
+target files to the file named by C<$hashref-E<gt>{write}>. If there is
+another file named by C<$hashref-E<gt>{read}>, the contents of this file will
 be merged into the written file. The read and the written file may be
 identical, but on AFS it is quite likely, people are installing to a
 different directory than the one where the files later appear.

lib/ExtUtils/MM_Unix.pm

@@ -42,8 +42,8 @@ overrides by defining rather primitive operations within
 ExtUtils::MM_Unix.
 
 If you are going to write a platform specific MM package, please try
-to limit the necessary overrides to primitiv methods, and if it is not
-possible to do so, let's work it out how to achieve that gain.
+to limit the necessary overrides to primitive methods, and if it is not
+possible to do so, let's work out how to achieve that gain.
 
 If you are overriding any of these methods in your Makefile.PL (in the
 MY class), please report that to the makemaker mailing list. We are
@@ -60,7 +60,7 @@ sections and complain loudly to the makemaker mailing list.
 Not all of the methods below are overridable in a
 Makefile.PL. Overridable methods are marked as (o). All methods are
 overridable by a platform specific MM_*.pm file (See
-L<ExtUtils::MM_VMS>) and L<ExtUtils::MM_OS2>).
+L<ExtUtils::MM_VMS> and L<ExtUtils::MM_OS2>).
 
 =head2 Preloaded methods
 
@@ -1031,7 +1031,7 @@ sub extliblist {
 
 =item file_name_is_absolute
 
-Takes as argument a path and returns true, it it is an absolute path.
+Takes as argument a path and returns true, if it is an absolute path.
 
 =cut
 
@@ -2475,7 +2475,7 @@ sub post_constants{
 
 =item post_initialize (o)
 
-Returns an ampty string per default. Used in Makefile.PLs to add some
+Returns an empty string per default. Used in Makefile.PLs to add some
 chunk of text to the Makefile after the object is initialized.
 
 =cut

lib/ExtUtils/MakeMaker.pm

@@ -1140,7 +1140,7 @@ so
 =item CONFIGURE
 
 CODE reference. The subroutine should return a hash reference. The
-hash may contain further attributes, e.g. {LIBS => ...}, that have to
+hash may contain further attributes, e.g. {LIBS =E<gt> ...}, that have to
 be determined by some evaluation method.
 
 =item DEFINE

lib/ExtUtils/Mksymlists.pm

@@ -153,7 +153,7 @@ ExtUtils::Mksymlists - write linker options files for dynamic extension
 =head1 DESCRIPTION
 
 C<ExtUtils::Mksymlists> produces files used by the linker under some OSs
-during the creation of shared libraries for synamic extensions.  It is
+during the creation of shared libraries for dynamic extensions.  It is
 normally called from a MakeMaker-generated Makefile when the extension
 is built.  The linker option file is generated by calling the function
 C<Mksymlists>, which is exported by default from C<ExtUtils::Mksymlists>.

lib/File/Copy.pm

@@ -192,8 +192,8 @@ associated with an old version of that file after C<rmscopy>
 returns, not the newly created version.)
 
 The third parameter is an integer flag, which tells C<rmscopy>
-how to handle timestamps.  If it is < 0, none of the input file's
-timestamps are propagated to the output file.  If it is > 0, then
+how to handle timestamps.  If it is E<lt> 0, none of the input file's
+timestamps are propagated to the output file.  If it is E<gt> 0, then
 it is interpreted as a bitmask: if bit 0 (the LSB) is set, then
 timestamps other than the revision date are propagated; if bit 1
 is set, the revision date is propagated.  If the third parameter

lib/File/Path.pm

@@ -78,8 +78,8 @@ treated as ordinary files.
 
 =head1 AUTHORS
 
-Tim Bunce <Tim.Bunce@ig.co.uk>
-Charles Bailey <bailey@genetics.upenn.edu>
+Tim Bunce E<lt>F<Tim.Bunce@ig.co.uk>E<gt>
+Charles Bailey E<lt>F<bailey@genetics.upenn.edu>E<gt>
 
 =head1 REVISION
 

lib/FindBin.pm

@@ -24,7 +24,7 @@ Locates the full path to the script bin directory to allow the use
 of paths relative to the bin directory.
 
 This allows a user to setup a directory tree for some software with
-directories <root>/bin and <root>/lib and then the above example will allow
+directories E<lt>rootE<gt>/bin and E<lt>rootE<gt>/lib and then the above example will allow
 the use of modules in the lib directory without knowing where the software
 tree is installed.
 
@@ -55,8 +55,8 @@ Workaround is to invoke perl as
 
 =head1 AUTHORS
 
-Graham Barr <bodg@tiuk.ti.com>
-Nick Ing-Simmons <nik@tiuk.ti.com>
+Graham Barr E<lt>F<bodg@tiuk.ti.com>E<gt>
+Nick Ing-Simmons E<lt>F<nik@tiuk.ti.com>E<gt>
 
 =head1 COPYRIGHT