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.

2 files changed, 81 insertions, 78 deletions

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: $!";