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.

8 files changed, 42 insertions, 45 deletions

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).