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.

43 files changed, 246 insertions, 240 deletions

diff --git a/configpm b/configpm
index 37fe925252..eab7f5bea4 100755
--- a/configpm
+++ b/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
diff --git a/ext/DynaLoader/DynaLoader.pm b/ext/DynaLoader/DynaLoader.pm
index 282d364372..b634aef051 100644
--- a/ext/DynaLoader/DynaLoader.pm
+++ b/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:
 
diff --git a/ext/FileHandle/FileHandle.pm b/ext/FileHandle/FileHandle.pm
index 1c030ecd34..d479dae08c 100644
--- a/ext/FileHandle/FileHandle.pm
+++ b/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.
 
diff --git a/ext/Opcode/Safe.pm b/ext/Opcode/Safe.pm
index f15dbd55e8..6007b97311 100644
--- a/ext/Opcode/Safe.pm
+++ b/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
 
diff --git a/ext/Socket/Socket.pm b/ext/Socket/Socket.pm
index bae8a3759e..9872d03526 100644
--- a/ext/Socket/Socket.pm
+++ b/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
 
diff --git a/installman b/installman
index 5e0b0cc596..d57cdb14e9 100755
--- a/installman
+++ b/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;
diff --git a/installperl b/installperl
index 346e8351aa..183c3edbc4 100755
--- a/installperl
+++ b/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,6 +116,11 @@ 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) {
@@ -127,30 +128,6 @@ foreach $file (@pods) {
     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;
diff --git a/lib/Cwd.pm b/lib/Cwd.pm
index 1512d7f212..e4e94b3064 100644
--- a/lib/Cwd.pm
+++ b/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
 
diff --git a/lib/Devel/SelfStubber.pm b/lib/Devel/SelfStubber.pm
index fc7ee4b511..7bb38f6957 100644
--- a/lib/Devel/SelfStubber.pm
+++ b/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
diff --git a/lib/Env.pm b/lib/Env.pm
index 0e790754a8..63beb07508 100644
--- a/lib/Env.pm
+++ b/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
 
diff --git a/lib/Exporter.pm b/lib/Exporter.pm
index e374414505..fd95a7efef 100644
--- a/lib/Exporter.pm
+++ b/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.
 
diff --git a/lib/ExtUtils/Install.pm b/lib/ExtUtils/Install.pm
index 86e7787b56..dda132565f 100644
--- a/lib/ExtUtils/Install.pm
+++ b/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.
diff --git a/lib/ExtUtils/MM_Unix.pm b/lib/ExtUtils/MM_Unix.pm
index aba04e3274..b3356d9505 100644
--- a/lib/ExtUtils/MM_Unix.pm
+++ b/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
diff --git a/lib/ExtUtils/MakeMaker.pm b/lib/ExtUtils/MakeMaker.pm
index e75f28f639..027c1fe6e9 100644
--- a/lib/ExtUtils/MakeMaker.pm
+++ b/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
diff --git a/lib/ExtUtils/Mksymlists.pm b/lib/ExtUtils/Mksymlists.pm
index 47c37bf623..0f9a132c36 100644
--- a/lib/ExtUtils/Mksymlists.pm
+++ b/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>.
diff --git a/lib/File/Copy.pm b/lib/File/Copy.pm
index aedcd7fb03..92b9be15e6 100644
--- a/lib/File/Copy.pm
+++ b/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
diff --git a/lib/File/Path.pm b/lib/File/Path.pm
index 97cb66855d..8d775d52d5 100644
--- a/lib/File/Path.pm
+++ b/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
 
diff --git a/lib/FindBin.pm b/lib/FindBin.pm
index 4bfc098f1e..242ea5f57b 100644
--- a/lib/FindBin.pm
+++ b/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
 
diff --git a/lib/Getopt/Long.pm b/lib/Getopt/Long.pm
index 3fa9c8b10f..190b609571 100644
--- a/lib/Getopt/Long.pm
+++ b/lib/Getopt/Long.pm
@@ -85,7 +85,7 @@ followed by an argument specifier. Values for argument specifiers are:
 
 =over 8
 
-=item <none>
+=item E<lt>noneE<gt>
 
 Option does not take an argument. 
 The option variable will be set to 1.
@@ -208,7 +208,7 @@ The option name is always the true name, not an abbreviation or alias.
 
 The option name may actually be a list of option names, separated by
 "|"s, e.g. "foo|bar|blech=s". In this example, "foo" is the true name
-op this option. If no linkage is specified, options "foo", "bar" and
+of this option. If no linkage is specified, options "foo", "bar" and
 "blech" all will set $opt_foo.
 
 Option names may be abbreviated to uniqueness, depending on
@@ -216,7 +216,7 @@ configuration variable $Getopt::Long::autoabbrev.
 
 =head2 Non-option call-back routine
 
-A special option specifier, <>, can be used to designate a subroutine
+A special option specifier, E<lt>E<gt>, can be used to designate a subroutine
 to handle non-option arguments. GetOptions will immediately call this
 subroutine for every non-option it encounters in the options list.
 This subroutine gets the name of the non-option passed.
@@ -285,18 +285,18 @@ In GNU or POSIX format, option names and values can be combined:
    --bar=		-> $opt_bar = ''
    --bar=--		-> $opt_bar = '--'
 
-Example of using variabel references:
+Example of using variable references:
 
    $ret = &GetOptions ('foo=s', \$foo, 'bar=i', 'ar=s', \@ar);
 
 With command line options "-foo blech -bar 24 -ar xx -ar yy" 
 this will result in:
 
-   $bar = 'blech'
+   $foo = 'blech'
    $opt_bar = 24
    @ar = ('xx','yy')
 
-Example of using the <> option specifier:
+Example of using the E<lt>E<gt> option specifier:
 
    @ARGV = qw(-foo 1 bar -foo 2 blech);
    &GetOptions("foo=i", \$myfoo, "<>", \&mysub);
diff --git a/lib/IPC/Open2.pm b/lib/IPC/Open2.pm
index 62ec69b335..35bb0d1f16 100644
--- a/lib/IPC/Open2.pm
+++ b/lib/IPC/Open2.pm
@@ -20,7 +20,7 @@ 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");
+    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:/>.
diff --git a/lib/IPC/Open3.pm b/lib/IPC/Open3.pm
index fc93ab548d..d416ae7886 100644
--- a/lib/IPC/Open3.pm
+++ b/lib/IPC/Open3.pm
@@ -19,9 +19,9 @@ 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
+If WTRFH begins with "E<lt>&", 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
+"E<gt>&", 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.
 
 If you try to read from the child's stdout writer and their stderr
diff --git a/lib/Pod/Text.pm b/lib/Pod/Text.pm
index 1411587538..4faed4904e 100644
--- a/lib/Pod/Text.pm
+++ b/lib/Pod/Text.pm
@@ -28,13 +28,13 @@ A separate F<pod2text> program is included that is primarily a wrapper for
 Pod::Text.
 
 The single function C<pod2text()> can take one or two arguments. The first
-should be the name of a file to read the pod from, or "<&STDIN" to read from
+should be the name of a file to read the pod from, or "E<lt>&STDIN" to read from
 STDIN. A second argument, if provided, should be a filehandle glob where
 output should be sent.
 
 =head1 AUTHOR
 
-Tom Christiansen E<lt>tchrist@mox.perl.comE<gt>
+Tom Christiansen E<lt>F<tchrist@mox.perl.com>E<gt>
 
 =head1 TODO
 
diff --git a/lib/SelfLoader.pm b/lib/SelfLoader.pm
index 136d42bef1..11dc6a24bf 100644
--- a/lib/SelfLoader.pm
+++ b/lib/SelfLoader.pm
@@ -230,7 +230,7 @@ that filehandle (and ONLY if you want to), you should either
 the C<__DATA__> token and put your own data after those
 declarations, using the C<__END__> token to mark the end
 of subroutine declarations. You must also ensure that the B<SelfLoader>
-reads first by  calling 'SelfLoader->load_stubs();', or by using a
+reads first by  calling 'SelfLoader-E<gt>load_stubs();', or by using a
 function which is selfloaded;
 
 or
@@ -258,7 +258,7 @@ need for stubs as far as autoloading is concerned.
 For modules which ARE classes, and need to handle inherited methods,
 stubs are needed to ensure that the method inheritance mechanism works
 properly. You can load the stubs into the module at 'require' time, by
-adding the statement 'SelfLoader->load_stubs();' to the module to do
+adding the statement 'SelfLoader-E<gt>load_stubs();' to the module to do
 this.
 
 The alternative is to put the stubs in before the C<__DATA__> token BEFORE
diff --git a/lib/Sys/Hostname.pm b/lib/Sys/Hostname.pm
index d527e4525f..ec04efc889 100644
--- a/lib/Sys/Hostname.pm
+++ b/lib/Sys/Hostname.pm
@@ -25,7 +25,7 @@ All nulls, returns, and newlines are removed from the result.
 
 =head1 AUTHOR
 
-David Sundstrom <sunds@asictest.sc.ti.com>
+David Sundstrom E<lt>F<sunds@asictest.sc.ti.com>E<gt>
 
 Texas Instruments
 
diff --git a/lib/Term/Complete.pm b/lib/Term/Complete.pm
index 6faef2296e..884f83fa90 100644
--- a/lib/Term/Complete.pm
+++ b/lib/Term/Complete.pm
@@ -28,7 +28,7 @@ The following command characters are defined:
 
 =over 4
 
-=item <tab>
+=item E<lt>tabE<gt>
 Attempts word completion.
 Cannot be changed.
 
@@ -42,7 +42,7 @@ Defined by I<$Term::Complete::complete>.
 Erases the current input.
 Defined by I<$Term::Complete::kill>.
 
-=item <del>, <bs>
+=item E<lt>delE<gt>, E<lt>bsE<gt>
 
 Erases one character.
 Defined by I<$Term::Complete::erase1> and I<$Term::Complete::erase2>.
@@ -55,7 +55,7 @@ Bell sounds when word completion fails.
 
 =head1 BUGS
 
-The completion charater <tab> cannot be changed.
+The completion charater E<lt>tabE<gt> cannot be changed.
 
 =head1 AUTHOR
 
diff --git a/lib/Term/ReadLine.pm b/lib/Term/ReadLine.pm
index 2ce7423186..88fc6386c3 100644
--- a/lib/Term/ReadLine.pm
+++ b/lib/Term/ReadLine.pm
@@ -33,7 +33,7 @@ or as
 
   $term->addhistory('row');
 
-where $term is a return value of Term::ReadLine->Init.
+where $term is a return value of Term::ReadLine-E<gt>Init.
 
 =over 12
 
@@ -74,7 +74,7 @@ history. Returns the old value.
 =item C<findConsole>
 
 returns an array with two strings that give most appropriate names for
-files for input and output using conventions C<"<$in">, C<"E<gt>out">.
+files for input and output using conventions C<"E<lt>$in">, C<"E<gt>out">.
 
 =item C<Features>
 
diff --git a/lib/Text/Tabs.pm b/lib/Text/Tabs.pm
index 8cc0d92f23..4024d7b685 100644
--- a/lib/Text/Tabs.pm
+++ b/lib/Text/Tabs.pm
@@ -69,15 +69,15 @@ __END__
 
 =head1 NAME
 
-Text::Tabs -- expand and unexpand tabs per the unix expand(1) and unexpand(1)
+Text::Tabs - expand and unexpand tabs per the unix expand(1) and unexpand(1)
 
 =head1 SYNOPSIS
 
-use Text::Tabs;
+    use Text::Tabs;
 
-$tabstop = 4;
-@lines_without_tabs = expand(@lines_with_tabs);
-@lines_with_tabs = unexpand(@lines_without_tabs);
+    $tabstop = 4;
+    @lines_without_tabs = expand(@lines_with_tabs);
+    @lines_with_tabs = unexpand(@lines_without_tabs);
 
 =head1 DESCRIPTION
 
@@ -94,4 +94,4 @@ entire document in one string.  Instead feed it an array of lines.
 
 =head1 AUTHOR
 
-David Muir Sharnoff <muir@idiom.com>
+David Muir Sharnoff E<lt>F<muir@idiom.com>E<gt>
diff --git a/lib/Text/Wrap.pm b/lib/Text/Wrap.pm
index 03bae1b8f9..2ffc69ec20 100644
--- a/lib/Text/Wrap.pm
+++ b/lib/Text/Wrap.pm
@@ -95,6 +95,6 @@ should be set to the full width of your output device.
 
 =head1 AUTHOR
 
-David Muir Sharnoff <muir@idiom.com>
+David Muir Sharnoff E<lt>F<muir@idiom.com>E<gt>
 
 =cut
diff --git a/lib/Time/Local.pm b/lib/Time/Local.pm
index 40e8da796b..1fab298e0a 100644
--- a/lib/Time/Local.pm
+++ b/lib/Time/Local.pm
@@ -8,7 +8,7 @@ use Carp;
 
 =head1 NAME
 
-Time::Local - efficiently compute tome from local and GMT time
+Time::Local - efficiently compute time from local and GMT time
 
 =head1 SYNOPSIS
 
diff --git a/lib/diagnostics.pm b/lib/diagnostics.pm
index f20b956b7d..a8af08f8c2 100755
--- a/lib/diagnostics.pm
+++ b/lib/diagnostics.pm
@@ -41,9 +41,9 @@ Aa a program:
 =head2 The C<diagnostics> Pragma
 
 This module extends the terse diagnostics normally emitted by both the
-perl compiler and the perl interpeter, augmenting them wtih the more
+perl compiler and the perl interpeter, augmenting them with the more
 explicative and endearing descriptions found in L<perldiag>.  Like the
-other pragmata, it affects to compilation phase of your program rather
+other pragmata, it affects the compilation phase of your program rather
 than merely the execution phase.
 
 To use in your program as a pragma, merely invoke
@@ -62,8 +62,8 @@ However, you may control there behaviour at runtime using the
 disable() and enable() methods to turn them off and on respectively.
 
 The B<-verbose> flag first prints out the L<perldiag> introduction before
-any other diagnostics.  The $diagnostics::PRETTY can generate nicer escape
-sequences for pgers.
+any other diagnostics.  The $diagnostics::PRETTY variable can generate nicer
+escape sequences for pagers.
 
 =head2 The I<splain> Program
 
@@ -98,7 +98,7 @@ afterwards, do this:
     ./splain < test.out
 
 Note that this is not in general possible in shells of more dubious heritage, 
-as the theorectical 
+as the theoretical 
 
     (perl -w test.pl >/dev/tty) >& test.out
     ./splain < test.out
@@ -143,7 +143,7 @@ runtime.  Otherwise, they may be embedded in the file itself when the
 splain package is built.   See the F<Makefile> for details.
 
 If an extant $SIG{__WARN__} handler is discovered, it will continue
-to be honored, but only after the diagnostic::splainthis() function 
+to be honored, but only after the diagnostics::splainthis() function 
 (the module's $SIG{__WARN__} interceptor) has had its way with your
 warnings.
 
diff --git a/lib/overload.pm b/lib/overload.pm
index 28e7d0b3e7..20411ea576 100644
--- a/lib/overload.pm
+++ b/lib/overload.pm
@@ -203,7 +203,7 @@ postfix form.
     "atan2", "cos", "sin", "exp", "abs", "log", "sqrt",
 
 If C<abs> is unavailable, it can be autogenerated using methods
-for "<" or "<=>" combined with either unary minus or subtraction.
+for "E<lt>" or "E<lt>=E<gt>" combined with either unary minus or subtraction.
 
 =item * I<Boolean, string and numeric conversion>
 
@@ -376,7 +376,7 @@ can be expressed in terms of string conversion.
 
 can be expressed in terms of its "spaceship" counterpart: either
 C<E<lt>=E<gt>> or C<cmp>:
- 
+
     <, >, <=, >=, ==, != 	in terms of <=>
     lt, gt, le, ge, eq, ne 	in terms of cmp
 
@@ -476,7 +476,7 @@ to be changed are constant (but this is not enforced).
 
 =head1 AUTHOR
 
-Ilya Zakharevich <F<ilya@math.mps.ohio-state.edu>>.
+Ilya Zakharevich E<lt>F<ilya@math.mps.ohio-state.edu>E<gt>.
 
 =head1 DIAGNOSTICS
 
diff --git a/lib/splain b/lib/splain
index f20b956b7d..a8af08f8c2 100755
--- a/lib/splain
+++ b/lib/splain
@@ -41,9 +41,9 @@ Aa a program:
 =head2 The C<diagnostics> Pragma
 
 This module extends the terse diagnostics normally emitted by both the
-perl compiler and the perl interpeter, augmenting them wtih the more
+perl compiler and the perl interpeter, augmenting them with the more
 explicative and endearing descriptions found in L<perldiag>.  Like the
-other pragmata, it affects to compilation phase of your program rather
+other pragmata, it affects the compilation phase of your program rather
 than merely the execution phase.
 
 To use in your program as a pragma, merely invoke
@@ -62,8 +62,8 @@ However, you may control there behaviour at runtime using the
 disable() and enable() methods to turn them off and on respectively.
 
 The B<-verbose> flag first prints out the L<perldiag> introduction before
-any other diagnostics.  The $diagnostics::PRETTY can generate nicer escape
-sequences for pgers.
+any other diagnostics.  The $diagnostics::PRETTY variable can generate nicer
+escape sequences for pagers.
 
 =head2 The I<splain> Program
 
@@ -98,7 +98,7 @@ afterwards, do this:
     ./splain < test.out
 
 Note that this is not in general possible in shells of more dubious heritage, 
-as the theorectical 
+as the theoretical 
 
     (perl -w test.pl >/dev/tty) >& test.out
     ./splain < test.out
@@ -143,7 +143,7 @@ runtime.  Otherwise, they may be embedded in the file itself when the
 splain package is built.   See the F<Makefile> for details.
 
 If an extant $SIG{__WARN__} handler is discovered, it will continue
-to be honored, but only after the diagnostic::splainthis() function 
+to be honored, but only after the diagnostics::splainthis() function 
 (the module's $SIG{__WARN__} interceptor) has had its way with your
 warnings.
 
diff --git a/lib/strict.pm b/lib/strict.pm
index a1c51531e9..4aa55eb4f3 100644
--- a/lib/strict.pm
+++ b/lib/strict.pm
@@ -56,7 +56,7 @@ name without fully qualifying it.
 
 This disables the poetry optimization, generating a compile-time error if
 you try to use a bareword identifier that's not a subroutine, unless it
-appears in curly braces or on the left hand side of the "=>" symbol.
+appears in curly braces or on the left hand side of the "=E<gt>" symbol.
 
 
     use strict 'subs';
diff --git a/pod/buildtoc b/pod/buildtoc
index 9ca5e920fd..8a9b7ff5cb 100644
--- a/pod/buildtoc
+++ b/pod/buildtoc
@@ -2,11 +2,13 @@ use File::Find;
 use Cwd;
 
 @pods = qw{
-	    perl perldata perlsyn perlop perlre perlrun perlfunc perlvar
-	    perlsub perlmod perlref perldsc perllol perlobj perltie
-	    perlbot perldebug perldiag perlform perlipc perlsec perltrap
-	    perlstyle perlxs perlxstut perlguts perlcall perlembed perlpod
-	    perlbook 
+	    perl
+	    perldata perlsyn perlop perlre perlrun perlfunc perlvar
+	        perlsub perlmod perlform
+	    perlref perldsc perllol perlobj perltie perlbot perlipc
+	    perldebug perldiag perlsec perltrap perlstyle
+	    perlpod perlbook
+	    perlembed perlapio perlxs perlxstut perlguts perlcall
 	};
 for (@pods) { s/$/.pod/ } 
 
@@ -100,7 +102,7 @@ podset( @modules[ sort { $modname[$a] cmp $modname[$b] } 0 .. $#modules ] );
 
 	=head1 AUXILIARY DOCUMENTATION
 
-	Here should be listed all the extra program's docs, but they
+	Here should be listed all the extra programs' docs, but they
 	don't all have man pages yet:
 
 	=item a2p
diff --git a/pod/perldsc.pod b/pod/perldsc.pod
index 6d31976852..6991e7a085 100644
--- a/pod/perldsc.pod
+++ b/pod/perldsc.pod
@@ -509,7 +509,7 @@ types of data structures.
 
  # calling a function  that returns a key,value list, like
  # "lead","fred","daughter","pebbles"
- while ( %fields = getnextpairset() )
+ while ( %fields = getnextpairset() ) {
      push @LoH, { %fields };
  }
 
@@ -601,12 +601,6 @@ types of data structures.
      }
  }
 
- # calling a function  that returns a key,value list, like
- # "lead","fred","daughter","pebbles"
- while ( %fields = getnextpairset() )
-     push @a, { %fields };
- }
-
  # calling a function  that returns a key,value hash
  for $group ( "simpsons", "jetsons", "flintstones" ) {
      $HoH{$group} = { get_family($group) };
@@ -638,7 +632,7 @@ types of data structures.
 
  # print the whole thing
  foreach $family ( keys %HoH ) {
-     print "$family: ";
+     print "$family: { ";
      for $role ( keys %{ $HoH{$family} } ) {
          print "$role=$HoH{$family}{$role} ";
      }
@@ -647,7 +641,7 @@ types of data structures.
 
  # print the whole thing  somewhat sorted
  foreach $family ( sort keys %HoH ) {
-     print "$family: ";
+     print "$family: { ";
      for $role ( sort keys %{ $HoH{$family} } ) {
          print "$role=$HoH{$family}{$role} ";
      }
@@ -657,7 +651,7 @@ types of data structures.
 
  # print the whole thing sorted by number of members
  foreach $family ( sort { keys %{$HoH{$b}} <=> keys %{$HoH{$b}} } keys %HoH ) {
-     print "$family: ";
+     print "$family: { ";
      for $role ( sort keys %{ $HoH{$family} } ) {
          print "$role=$HoH{$family}{$role} ";
      }
@@ -670,9 +664,9 @@ types of data structures.
 
  # now print the whole thing sorted by number of members
  foreach $family ( sort { keys %{$HoH{$b}} <=> keys %{$HoH{$b}} } keys %HoH ) {
-     print "$family: ";
+     print "$family: { ";
      # and print these according to rank order
-     for $role ( sort { $rank{$a} <=> $rank{$b} keys %{ $HoH{$family} } ) {
+     for $role ( sort { $rank{$a} <=> $rank{$b} keys %{ $HoH{$family} } } ) {
          print "$role=$HoH{$family}{$role} ";
      }
      print "}\n";
@@ -762,7 +756,7 @@ many different sorts:
 
      @members = ();
      # assume this file in field=value syntax
-     while () {
+     while (<>) {
          %fields = split /[\s=]+/;
          push @members, { %fields };
      }
@@ -829,7 +823,7 @@ source code to MLDBM.
 
 =head1 SEE ALSO
 
-L<perlref>, L<perllol>, L<perldata>, L<perlobj>
+perlref(1), perllol(1), perldata(1), perlobj(1)
 
 =head1 AUTHOR
 
diff --git a/pod/perlform.pod b/pod/perlform.pod
index 8c840d4cc2..a9ce4a7876 100644
--- a/pod/perlform.pod
+++ b/pod/perlform.pod
@@ -54,7 +54,7 @@ with either "@" (at) or "^" (caret).  These lines do not undergo any kind
 of variable interpolation.  The at field (not to be confused with the array
 marker @) is the normal kind of field; the other kind, caret fields, are used
 to do rudimentary multi-line text block filling.  The length of the field
-is supplied by padding out the field with multiple "<", ">", or "|"
+is supplied by padding out the field with multiple "E<lt>", "E<gt>", or "|"
 characters to specify, respectively, left justification, right
 justification, or centering.  If the variable would exceed the width
 specified, it is truncated.
@@ -147,18 +147,18 @@ Examples:
  .
 
 It is possible to intermix print()s with write()s on the same output
-channel, but you'll have to handle $- ($FORMAT_LINES_LEFT)
+channel, but you'll have to handle C<$-> (C<$FORMAT_LINES_LEFT>)
 yourself.
 
 =head2 Format Variables
 
-The current format name is stored in the variable C<$~> ($FORMAT_NAME),
-and the current top of form format name is in C<$^> ($FORMAT_TOP_NAME).
-The current output page number is stored in C<$%> ($FORMAT_PAGE_NUMBER),
-and the number of lines on the page is in C<$=> ($FORMAT_LINES_PER_PAGE).
+The current format name is stored in the variable C<$~> (C<$FORMAT_NAME>),
+and the current top of form format name is in C<$^> (C<$FORMAT_TOP_NAME>).
+The current output page number is stored in C<$%> (C<$FORMAT_PAGE_NUMBER>),
+and the number of lines on the page is in C<$=> (C<$FORMAT_LINES_PER_PAGE>).
 Whether to autoflush output on this handle is stored in C<$|>
-($OUTPUT_AUTOFLUSH).  The string output before each top of page (except
-the first) is stored in C<$^L> ($FORMAT_FORMFEED).  These variables are
+(C<$OUTPUT_AUTOFLUSH>).  The string output before each top of page (except
+the first) is stored in C<$^L> (C<$FORMAT_FORMFEED>).  These variables are
 set on a per-filehandle basis, so you'll need to select() into a different
 one to affect them:
 
diff --git a/pod/perllol.pod b/pod/perllol.pod
index a1e8a2deef..c97aac918d 100644
--- a/pod/perllol.pod
+++ b/pod/perllol.pod
@@ -12,7 +12,7 @@ that applies here will also be applicable later on with the fancier data
 structures.
 
 A list of lists, or an array of an array if you would, is just a regular
-old array @LoL that you can get at with two subscripts, like $LoL[3][2].  Here's
+old array @LoL that you can get at with two subscripts, like C<$LoL[3][2]>.  Here's
 a declaration of the array:
 
     # assign to our array a list of list references
@@ -42,7 +42,7 @@ but rather just a reference to it, you could do something more like this:
 Notice that the outer bracket type has changed, and so our access syntax 
 has also changed.  That's because unlike C, in perl you can't freely
 interchange arrays and references thereto.  $ref_to_LoL is a reference to an 
-array, whereas @LoL is an array proper.  Likewise, $LoL[2] is not an 
+array, whereas @LoL is an array proper.  Likewise, C<$LoL[2]> is not an 
 array, but an array ref.  So how come you can write these:
 
     $LoL[2][2]
@@ -54,7 +54,7 @@ instead of having to write these:
     $ref_to_LoL->[2]->[2]
 
 Well, that's because the rule is that on adjacent brackets only (whether
-square or curly), you are free to omit the pointer dereferencing array.
+square or curly), you are free to omit the pointer dereferencing arrow.
 But you cannot do so for the very first one if it's a scalar containing
 a reference, which means that $ref_to_LoL always needs it.
 
@@ -116,7 +116,7 @@ You also don't have to use push().  You could just make a direct assignment
 if you knew where you wanted to put it:
 
     my (@LoL, $i, $line);
-    for $i ( 0 .. 10 ) 
+    for $i ( 0 .. 10 ) {
 	$line = <>;
 	$LoL[$i] = [ split ' ', $line ];
     } 
@@ -124,7 +124,7 @@ if you knew where you wanted to put it:
 or even just
 
     my (@LoL, $i);
-    for $i ( 0 .. 10 ) 
+    for $i ( 0 .. 10 ) {
 	$LoL[$i] = [ split ' ', <> ];
     } 
 
@@ -133,7 +133,7 @@ in a scalar context without explicitly stating such.
 This would be clearer to the casual reader:
 
     my (@LoL, $i);
-    for $i ( 0 .. 10 ) 
+    for $i ( 0 .. 10 ) {
 	$LoL[$i] = [ split ' ', scalar(<>) ];
     } 
 
@@ -308,6 +308,6 @@ perldata(1), perlref(1), perldsc(1)
 
 =head1 AUTHOR
 
-Tom Christiansen <tchrist@perl.com>
+Tom Christiansen E<lt>F<tchrist@perl.com>E<gt>
 
 Last udpate: Sat Oct  7 19:35:26 MDT 1995
diff --git a/pod/perlobj.pod b/pod/perlobj.pod
index acbd5314c8..54e052ff45 100644
--- a/pod/perlobj.pod
+++ b/pod/perlobj.pod
@@ -64,8 +64,9 @@ that wish to call methods in the class as part of the construction:
 	return $self;
     }
 
-If you care about inheritance (and you should; see L<perlmod/"Modules:
-Creation, Use and Abuse">), then you want to use the two-arg form of bless
+If you care about inheritance (and you should; see
+L<perlmod/"Modules: Creation, Use and Abuse">),
+then you want to use the two-arg form of bless
 so that your constructors may be inherited:
 
     sub new {
diff --git a/pod/perlrun.pod b/pod/perlrun.pod
index 3761398d4d..5042d67bd7 100644
--- a/pod/perlrun.pod
+++ b/pod/perlrun.pod
@@ -238,7 +238,7 @@ example in L<perlfunc/eof>).
 =item B<-I>I<directory>
 
 Directories specified by B<-I> are prepended to the search path for
-modules (@INC), and also tells the C preprocessor where to search for
+modules (C<@INC>), and also tells the C preprocessor where to search for
 include files.  The C preprocessor is invoked with B<-P>; by default it
 searches /usr/include and /usr/lib/perl.
 
@@ -259,7 +259,7 @@ separator if the B<-l> switch is followed by a B<-0> switch:
 
     gnufind / -print0 | perl -ln0e 'print "found $_" if -p'
 
-This sets $\ to newline and then sets $/ to the null character.
+This sets C<$\> to newline and then sets C<$/> to the null character.
 
 =item B<-m>[B<->]I<module>
 
diff --git a/pod/perlsec.pod b/pod/perlsec.pod
index 13c0987af7..facddedfbf 100644
--- a/pod/perlsec.pod
+++ b/pod/perlsec.pod
@@ -134,7 +134,7 @@ a child of lesser privilege.
 
 =head2 Cleaning Up Your Path
 
-For "Insecure $ENV{PATH}" messages, you need to set C<$ENV{'PATH'}> to a
+For "Insecure C<$ENV{PATH}>" messages, you need to set C<$ENV{'PATH'}> to a
 known value, and each directory in the path must be non-writable by others
 than its owner and group.  You may be surprised to get this message even
 if the pathname to your executable is fully qualified.  This is I<not>
diff --git a/pod/perlsub.pod b/pod/perlsub.pod
index 4d186d2843..870b2b5af9 100644
--- a/pod/perlsub.pod
+++ b/pod/perlsub.pod
@@ -58,7 +58,7 @@ indistinguishable list.
 Perl does not have named formal parameters, but in practice all you do is
 assign to a my() list of these.  Any variables you use in the function
 that aren't declared private are global variables.  For the gory details
-on creating private variables, see the sections below on
+on creating private variables, see
 L<"Private Variables via my()"> and L<"Temporary Values via local()">.
 To create protected environments for a set of functions in a separate
 package (and probably a separate file), see L<perlmod/"Packages">.
@@ -106,7 +106,7 @@ Use array assignment to a local list to name your formal arguments:
 
 This also has the effect of turning call-by-reference into call-by-value,
 since the assignment copies the values.  Otherwise a function is free to
-do in-place modifications of @_ and change its callers values.
+do in-place modifications of @_ and change its caller's values.
 
     upcase_in($v1, $v2);  # this changes $v1 and $v2
     sub upcase_in {
@@ -362,7 +362,7 @@ Synopsis:
     local *merlyn = \$randal;   # just alias $merlyn, not @merlyn etc 
 
 A local() modifies its listed variables to be local to the enclosing
-block, (or subroutine, C<eval{}> or C<do>) and I<the any called from
+block, (or subroutine, C<eval{}> or C<do>) and I<any called from
 within that block>.  A local() just gives temporary values to global
 (meaning package) variables.  This is known as dynamic scoping.  Lexical
 scoping is done with "my", which works more like C's auto declarations.
@@ -392,7 +392,7 @@ subroutine.  Examples:
     }
     # old %digits restored here
 
-Because local() is a run-time command, and so gets executed every time
+Because local() is a run-time command, it gets executed every time
 through a loop.  In releases of Perl previous to 5.0, this used more stack
 storage each time until the loop was exited.  Perl now reclaims the space
 each time through, but it's still more efficient to declare your variables
@@ -442,7 +442,7 @@ whatever "*" value was assigned to it.  Example:
 
 Note that scalars are already passed by reference, so you can modify
 scalar arguments without using this mechanism by referring explicitly
-to $_[0] etc.  You can modify all the elements of an array by passing
+to C<$_[0]> etc.  You can modify all the elements of an array by passing
 all the elements as scalars, but you have to use the * mechanism (or
 the equivalent reference mechanism) to push, pop or change the size of
 an array.  It will certainly be faster to pass the typeglob (or reference).
diff --git a/utils/c2ph.PL b/utils/c2ph.PL
index 219af02933..97d17af655 100644
--- a/utils/c2ph.PL
+++ b/utils/c2ph.PL
@@ -46,7 +46,7 @@ print OUT <<'!NO!SUBS!';
 
 =head1 NAME
 
-c2ph,pstruct - Dump C structures as generated from 'cc -g -S' stabs
+c2ph, pstruct - Dump C structures as generated from C<cc -g -S> stabs
 
 =head1 SYNOPSIS
 
@@ -95,44 +95,44 @@ Pstruct takes any .c or .h files, or preferably .s ones, since that's
 the format it is going to massage them into anyway, and spits out
 listings like this:
 
-struct tty {
-  int                          tty.t_locker                         000      4
-  int                          tty.t_mutex_index                    004      4
-  struct tty *                 tty.t_tp_virt                        008      4
-  struct clist                 tty.t_rawq                           00c     20
-    int                        tty.t_rawq.c_cc                      00c      4
-    int                        tty.t_rawq.c_cmax                    010      4
-    int                        tty.t_rawq.c_cfx                     014      4
-    int                        tty.t_rawq.c_clx                     018      4
-    struct tty *               tty.t_rawq.c_tp_cpu                  01c      4
-    struct tty *               tty.t_rawq.c_tp_iop                  020      4
-    unsigned char *            tty.t_rawq.c_buf_cpu                 024      4
-    unsigned char *            tty.t_rawq.c_buf_iop                 028      4
-  struct clist                 tty.t_canq                           02c     20
-    int                        tty.t_canq.c_cc                      02c      4
-    int                        tty.t_canq.c_cmax                    030      4
-    int                        tty.t_canq.c_cfx                     034      4
-    int                        tty.t_canq.c_clx                     038      4
-    struct tty *               tty.t_canq.c_tp_cpu                  03c      4
-    struct tty *               tty.t_canq.c_tp_iop                  040      4
-    unsigned char *            tty.t_canq.c_buf_cpu                 044      4
-    unsigned char *            tty.t_canq.c_buf_iop                 048      4
-  struct clist                 tty.t_outq                           04c     20
-    int                        tty.t_outq.c_cc                      04c      4
-    int                        tty.t_outq.c_cmax                    050      4
-    int                        tty.t_outq.c_cfx                     054      4
-    int                        tty.t_outq.c_clx                     058      4
-    struct tty *               tty.t_outq.c_tp_cpu                  05c      4
-    struct tty *               tty.t_outq.c_tp_iop                  060      4
-    unsigned char *            tty.t_outq.c_buf_cpu                 064      4
-    unsigned char *            tty.t_outq.c_buf_iop                 068      4
-  (*int)()                     tty.t_oproc_cpu                      06c      4
-  (*int)()                     tty.t_oproc_iop                      070      4
-  (*int)()                     tty.t_stopproc_cpu                   074      4
-  (*int)()                     tty.t_stopproc_iop                   078      4
-  struct thread *              tty.t_rsel                           07c      4
-
-  etc.
+ struct tty {
+   int                          tty.t_locker                         000      4
+   int                          tty.t_mutex_index                    004      4
+   struct tty *                 tty.t_tp_virt                        008      4
+   struct clist                 tty.t_rawq                           00c     20
+     int                        tty.t_rawq.c_cc                      00c      4
+     int                        tty.t_rawq.c_cmax                    010      4
+     int                        tty.t_rawq.c_cfx                     014      4
+     int                        tty.t_rawq.c_clx                     018      4
+     struct tty *               tty.t_rawq.c_tp_cpu                  01c      4
+     struct tty *               tty.t_rawq.c_tp_iop                  020      4
+     unsigned char *            tty.t_rawq.c_buf_cpu                 024      4
+     unsigned char *            tty.t_rawq.c_buf_iop                 028      4
+   struct clist                 tty.t_canq                           02c     20
+     int                        tty.t_canq.c_cc                      02c      4
+     int                        tty.t_canq.c_cmax                    030      4
+     int                        tty.t_canq.c_cfx                     034      4
+     int                        tty.t_canq.c_clx                     038      4
+     struct tty *               tty.t_canq.c_tp_cpu                  03c      4
+     struct tty *               tty.t_canq.c_tp_iop                  040      4
+     unsigned char *            tty.t_canq.c_buf_cpu                 044      4
+     unsigned char *            tty.t_canq.c_buf_iop                 048      4
+   struct clist                 tty.t_outq                           04c     20
+     int                        tty.t_outq.c_cc                      04c      4
+     int                        tty.t_outq.c_cmax                    050      4
+     int                        tty.t_outq.c_cfx                     054      4
+     int                        tty.t_outq.c_clx                     058      4
+     struct tty *               tty.t_outq.c_tp_cpu                  05c      4
+     struct tty *               tty.t_outq.c_tp_iop                  060      4
+     unsigned char *            tty.t_outq.c_buf_cpu                 064      4
+     unsigned char *            tty.t_outq.c_buf_iop                 068      4
+   (*int)()                     tty.t_oproc_cpu                      06c      4
+   (*int)()                     tty.t_oproc_iop                      070      4
+   (*int)()                     tty.t_stopproc_cpu                   074      4
+   (*int)()                     tty.t_stopproc_iop                   078      4
+   struct thread *              tty.t_rsel                           07c      4
+
+etc.
 
 
 Actually, this was generated by a particular set of options.  You can control
@@ -140,10 +140,10 @@ the formatting of each column, whether you prefer wide or fat, hex or decimal,
 leading zeroes or whatever.
 
 All you need to be able to use this is a C compiler than generates
-BSD/GCC-style stabs.  The -g option on native BSD compilers and GCC
+BSD/GCC-style stabs.  The B<-g> option on native BSD compilers and GCC
 should get this for you.
 
-To learn more, just type a bogus option, like -\?, and a long usage message
+To learn more, just type a bogus option, like B<-\?>, and a long usage message
 will be provided.  There are a fair number of possibilities.
 
 If you're only a C programmer, than this is the end of the message for you.
@@ -193,7 +193,7 @@ them in terms of packages and functions.  Consider the following program:
 
 
 As you see, the name of the package is the name of the structure.  Regular
-fields are just their own names.  Plus the follwoing  accessor functions are
+fields are just their own names.  Plus the following accessor functions are
 provided for your convenience:
 
     struct	This takes no arguments, and is merely the number of first-level
@@ -251,7 +251,7 @@ compiler and gcc.
 Anyway, here it is.  Should run on perl v4 or greater.  Maybe less.
 
 
---tom
+ --tom
 
 =cut
 
diff --git a/utils/h2ph.PL b/utils/h2ph.PL
index 4743dacde9..22161b9791 100644
--- a/utils/h2ph.PL
+++ b/utils/h2ph.PL
@@ -30,10 +30,6 @@ $Config{'startperl'}
     eval 'exec perl -S \$0 "\$@"'
 	if 0;
 
-'di ';
-'ds 00 \"';
-'ig 00 ';
-
 !GROK!THIS!
 
 # In the following, perl variables are not expanded during extraction.
@@ -253,56 +249,63 @@ sub expr {
     }
 }
 ##############################################################################
+__END__
+
+=head1 NAME
+
+h2ph - convert .h C header files to .ph Perl header files
+
+=head1 SYNOPSIS
+
+B<h2ph [headerfiles]>
+
+=head1 DESCRIPTION
 
-	# These next few lines are legal in both Perl and nroff.
-
-.00 ;			# finish .ig
-
-'di			\" finish diversion--previous line must be blank
-.nr nl 0-1		\" fake up transition to first page again
-.nr % 0			\" start at page 1
-'; __END__ ############# From here on it's a standard manual page ############
-.TH H2PH 1 "August 8, 1990"
-.AT 3
-.SH NAME
-h2ph \- convert .h C header files to .ph Perl header files
-.SH SYNOPSIS
-.B h2ph [headerfiles]
-.SH DESCRIPTION
-.I h2ph
+I<h2ph>
 converts any C header files specified to the corresponding Perl header file
 format.
 It is most easily run while in /usr/include:
-.nf
 
 	cd /usr/include; h2ph * sys/*
 
-.fi
 If run with no arguments, filters standard input to standard output.
-.SH ENVIRONMENT
+
+=head1 ENVIRONMENT
+
 No environment variables are used.
-.SH FILES
-/usr/include/*.h
-.br
-/usr/include/sys/*.h
-.br
+
+=head1 FILES
+
+ /usr/include/*.h
+ /usr/include/sys/*.h
+
 etc.
-.SH AUTHOR
+
+=head1 AUTHOR
+
 Larry Wall
-.SH "SEE ALSO"
+
+=head1 SEE ALSO
+
 perl(1)
-.SH DIAGNOSTICS
+
+=head1 DIAGNOSTICS
+
 The usual warnings if it can't read or write the files involved.
-.SH BUGS
+
+=head1 BUGS
+
 Doesn't construct the %sizeof array for you.
-.PP
+
 It doesn't handle all C constructs, but it does attempt to isolate
 definitions inside evals so that you can get at the definitions
 that it can translate.
-.PP
+
 It's only intended as a rough tool.
 You may need to dicker with the files produced.
-.ex
+
+=cut
+
 !NO!SUBS!
 
 close OUT or die "Can't close $file: $!";