add OO tutorial for beginners (from Randal L. Schwartz

<merlyn@stonehenge.com>)

p4raw-id: //depot/perl@5347

6 files changed, 1288 insertions, 203 deletions

diff --git a/pod/Makefile b/pod/Makefile
index 8199390e63..52f7e1e365 100644
--- a/pod/Makefile
+++ b/pod/Makefile
@@ -38,6 +38,7 @@ POD = \
 	perlreftut.pod	\
 	perldsc.pod	\
 	perllol.pod	\
+	perlboot.pod	\
 	perltoot.pod	\
 	perltootc.pod	\
 	perlobj.pod	\
@@ -102,6 +103,7 @@ MAN = \
 	perlreftut.man	\
 	perldsc.man	\
 	perllol.man	\
+	perlboot.man	\
 	perltoot.man	\
 	perltootc.man	\
 	perlobj.man	\
@@ -166,6 +168,7 @@ HTML = \
 	perlreftut.html	\
 	perldsc.html	\
 	perllol.html	\
+	perlboot.html	\
 	perltoot.html	\
 	perltootc.html	\
 	perlobj.html	\
@@ -230,6 +233,7 @@ TEX = \
 	perlreftut.tex	\
 	perldsc.tex	\
 	perllol.tex	\
+	perlboot.tex	\
 	perltoot.tex	\
 	perltootc.tex	\
 	perlobj.tex	\
diff --git a/pod/buildtoc b/pod/buildtoc
index f158cbaebb..dd8638ac0b 100644
--- a/pod/buildtoc
+++ b/pod/buildtoc
@@ -10,7 +10,7 @@ sub output ($);
 	   perlsyn perlop perlre perlrun perlfunc perlvar perlsub
 	   perlmod perlmodlib perlmodinstall perlfork perlform perllocale 
 	   perlref perlreftut perldsc
-	   perllol perltoot perltootc perlobj perltie perlbot perlipc
+	   perllol perlboot perltoot perltootc perlobj perltie perlbot perlipc
 	   perldbmfilter perldebug
 	   perldiag perlsec perltrap perlport perlstyle perlpod perlbook
 	   perlembed perlapio perlxs perlxstut perlguts perlcall perlcompile
diff --git a/pod/perl.pod b/pod/perl.pod
index d52aff30fa..9fc6c1dbd3 100644
--- a/pod/perl.pod
+++ b/pod/perl.pod
@@ -41,6 +41,7 @@ sections:
     perlref		Perl references, the rest of the story
     perldsc		Perl data structures intro
     perllol		Perl data structures: arrays of arrays
+    perlboot		Perl OO tutorial for beginners
     perltoot		Perl OO tutorial, part 1
     perltootc		Perl OO tutorial, part 2
     perlobj		Perl objects
diff --git a/pod/perlboot.pod b/pod/perlboot.pod
new file mode 100644
index 0000000000..dbf4fc998c
--- /dev/null
+++ b/pod/perlboot.pod
@@ -0,0 +1,799 @@
+=head1 NAME
+
+perlboot - Beginner's Object-Oriented Tutorial
+
+=head1 DESCRIPTION
+
+If you're not familiar with objects from other languages, some of the
+other Perl object documentation may be a little daunting, such as
+L<perlobj>, a basic reference in using objects, and L<perltoot>, which
+introduces readers to the pecularities of Perl's object system in a
+tutorial way.
+
+So, let's take a different approach, presuming no prior object
+experience. It helps if you know about subroutines (L<perlsub>),
+references (L<perlref> et. seq.), and packages (L<perlmod>), so become
+familiar with those first if you haven't already.
+
+=head2 If we could talk to the animals...
+
+Let's let the animals talk for a moment:
+
+    sub Cow::speak {
+      print "a Cow goes moooo!\n";
+    }
+    sub Horse::speak {
+      print "a Horse goes neigh!\n";
+    }
+    sub Sheep::speak {
+      print "a Sheep goes baaaah!\n"
+    }
+
+    Cow::speak;
+    Horse::speak;
+    Sheep::speak;
+
+This results in:
+
+    a Cow goes moooo!
+    a Horse goes neigh!
+    a Sheep goes baaaah!
+
+Nothing spectacular here.  Simple subroutines, albeit from separate
+packages, and called using the full package name.  So let's create
+an entire pasture:
+
+    # Cow::speak, Horse::speak, Sheep::speak as before
+    @pasture = qw(Cow Cow Horse Sheep Sheep);
+    foreach $animal (@pasture) {
+      &{$animal."::speak"};
+    }
+
+This results in:
+
+    a Cow goes moooo!
+    a Cow goes moooo!
+    a Horse goes neigh!
+    a Sheep goes baaaah!
+    a Sheep goes baaaah!
+
+Wow.  That symbolic coderef de-referencing there is pretty nasty.
+We're counting on C<no strict subs> mode, certainly not recommended
+for larger programs.  And why was that necessary?  Because the name of
+the package seems to be inseparable from the name of the subroutine we
+want to invoke within that package.
+
+Or is it?
+
+=head2 Introducing the method invocation arrow
+
+For now, let's say that C<Class-E<gt>method> invokes subroutine
+C<method> in package C<Class>.  (Here, "Class" is used in its
+"category" meaning, not its "scholastic" meaning.) That's not
+completely accurate, but we'll do this one step at a time.  Now let's
+use it like so:
+
+    # Cow::speak, Horse::speak, Sheep::speak as before
+    Cow->speak;
+    Horse->speak;
+    Sheep->speak;
+
+And once again, this results in:
+
+    a Cow goes moooo!
+    a Horse goes neigh!
+    a Sheep goes baaaah!
+
+That's not fun yet.  Same number of characters, all constant, no
+variables.  But yet, the parts are separable now.  Watch:
+
+    $a = "Cow";
+    $a->speak; # invokes Cow->speak
+
+Ahh!  Now that the package name has been parted from the subroutine
+name, we can use a variable package name.  And this time, we've got
+something that works even when C<use strict refs> is enabled.
+
+=head2 Invoking a barnyard
+
+Let's take that new arrow invocation and put it back in the barnyard
+example:
+
+    sub Cow::speak {
+      print "a Cow goes moooo!\n";
+    }
+    sub Horse::speak {
+      print "a Horse goes neigh!\n";
+    }
+    sub Sheep::speak {
+      print "a Sheep goes baaaah!\n"
+    }
+
+    @pasture = qw(Cow Cow Horse Sheep Sheep);
+    foreach $animal (@pasture) {
+      $animal->speak;
+    }
+
+There!  Now we have the animals all talking, and safely at that,
+without the use of symbolic coderefs.
+
+But look at all that common code.  Each of the C<speak> routines has a
+similar structure: a C<print> operator and a string that contains
+common text, except for two of the words.  It'd be nice if we could
+factor out the commonality, in case we decide later to change it all
+to C<says> instead of C<goes>.
+
+And we actually have a way of doing that without much fuss, but we
+have to hear a bit more about what the method invocation arrow is
+actually doing for us.
+
+=head2 The extra parameter of method invocation
+
+The invocation of:
+
+    Class->method(@args)
+
+attempts to invoke subroutine C<Class::method> as:
+
+    Class::method("Class", @args);
+
+(If the subroutine can't be found, "inheritance" kicks in, but we'll
+get to that later.)  This means that we get the class name as the
+first parameter.  So we can rewrite the C<Sheep> speaking subroutine
+as:
+
+    sub Sheep::speak {
+      my $class = shift;
+      print "a $class goes baaaah!\n";
+    }
+
+And the other two animals come out similarly:
+
+    sub Cow::speak {
+      my $class = shift;
+      print "a $class goes moooo!\n";
+    }
+    sub Horse::speak {
+      my $class = shift;
+      print "a $class goes neigh!\n";
+    }
+
+In each case, C<$class> will get the value appropriate for that
+subroutine.  But once again, we have a lot of similar structure.  Can
+we factor that out even further?  Yes, by calling another method in
+the same class.
+
+=head2 Calling a second method to simplify things
+
+Let's call out from C<speak> to a helper method called C<sound>.
+This method provides the constant text for the sound itself.
+
+    { package Cow;
+      sub sound { "moooo" }
+      sub speak {
+	my $class = shift;
+	print "a $class goes ", $class->sound, "!\n"
+      }
+    }
+
+Now, when we call C<Cow-E<gt>speak>, we get a C<$class> of C<Cow> in
+C<speak>.  This in turn selects the C<Cow-E<gt>sound> method, which
+returns C<moooo>.  But how different would this be for the C<Horse>?
+
+    { package Horse;
+      sub sound { "neigh" }
+      sub speak {
+	my $class = shift;
+	print "a $class goes ", $class->sound, "!\n"
+      }
+    }
+
+Only the name of the package and the specific sound change.  So can we
+somehow share the definition for C<speak> between the Cow and the
+Horse?  Yes, with inheritance!
+
+=head2 Inheriting the windpipes
+
+We'll define a common subroutine package called C<Animal>, with the
+definition for C<speak>:
+
+    { package Animal;
+      sub speak {
+	my $class = shift;
+	print "a $class goes ", $class->sound, "!\n"
+      }
+    }
+
+Then, for each animal, we say it "inherits" from C<Animal>, along
+with the animal-specific sound:
+
+    { package Cow;
+      @ISA = qw(Animal);
+      sub sound { "moooo" }
+    }
+
+Note the added C<@ISA> array.  We'll get to that in a minute.
+
+But what happens when we invoke C<Cow-E<gt>speak> now?
+
+First, Perl constructs the argument list.  In this case, it's just
+C<Cow>.  Then Perl looks for C<Cow::speak>.  But that's not there, so
+Perl checks for the inheritance array C<@Cow::ISA>.  It's there,
+and contains the single name C<Animal>.
+
+Perl next checks for C<speak> inside C<Animal> instead, as in
+C<Animal::speak>.  And that's found, so Perl invokes that subroutine
+with the already frozen argument list.
+
+Inside the C<Animal::speak> subroutine, C<$class> becomes C<Cow> (the
+first argument).  So when we get to the step of invoking
+C<$class-E<gt>sound>, it'll be looking for C<Cow-E<gt>sound>, which
+gets it on the first try without looking at C<@ISA>.  Success!
+
+=head2 A few notes about @ISA
+
+This magical C<@ISA> variable (pronounced "is a" not "ice-uh"), has
+declared that C<Cow> "is a" C<Animal>.  Note that it's an array,
+not a simple single value, because on rare occasions, it makes sense
+to have more than one parent class searched for the missing methods.
+
+If C<Animal> also had an C<@ISA>, then we'd check there too.  The
+search is recursive, depth-first, left-to-right in each C<@ISA>.
+Typically, each C<@ISA> has only one element (multiple elements means
+multiple inheritance and multiple headaches), so we get a nice tree of
+inheritance.
+
+When we turn on C<use strict>, we'll get complaints on C<@ISA>, since
+it's not a variable containing an explicit package name, nor is it a
+lexical ("my") variable.  We can't make it a lexical variable though,
+so there's a couple of straightforward ways to handle that.
+
+The easiest is to just spell the package name out:
+
+    @Cow::ISA = qw(Animal);
+
+Or allow it as an implictly named package variable:
+
+    package Cow;
+    use vars qw(@ISA);
+    @ISA = qw(Animal);
+
+If you're bringing in the class from outside, via an object-oriented
+module, you change:
+
+    package Cow;
+    use Animal;
+    use vars qw(@ISA);
+    @ISA = qw(Animal);
+
+into just:
+
+    package Cow;
+    use base qw(Animal);
+
+And that's pretty darn compact.
+
+=head2 Overriding the methods
+
+Let's add a mouse, which can barely be heard:
+
+    # Animal package from before
+    { package Mouse;
+      @ISA = qw(Animal);
+      sub sound { "squeak" }
+      sub speak {
+        my $class = shift;
+	print "a $class goes ", $class->sound, "!\n";
+	print "[but you can barely hear it!]\n";
+      }
+    }
+
+    Mouse->speak;
+
+which results in:
+
+    a Mouse goes squeak!
+    [but you can barely hear it!]
+
+Here, C<Mouse> has its own speaking routine, so C<Mouse-E<gt>speak>
+doesn't immediately invoke C<Animal-E<gt>speak>.  This is known as
+"overriding".  In fact, we didn't even need to say that a C<Mouse> was
+an C<Animal> at all, since all of the methods needed for C<speak> are
+completely defined with C<Mouse>.
+
+But we've now duplicated some of the code from C<Animal-E<gt>speak>,
+and this can once again be a maintenance headache.  So, can we avoid
+that?  Can we say somehow that a C<Mouse> does everything any other
+C<Animal> does, but add in the extra comment?  Sure!
+
+First, we can invoke the C<Animal::speak> method directly:
+
+    # Animal package from before
+    { package Mouse;
+      @ISA = qw(Animal);
+      sub sound { "squeak" }
+      sub speak {
+        my $class = shift;
+        Animal::speak($class);
+	print "[but you can barely hear it!]\n";
+      }
+    }
+
+Note that we have to include the C<$class> parameter (almost surely
+the value of C<"Mouse">) as the first parameter to C<Animal::speak>,
+since we've stopped using the method arrow.  Why did we stop?  Well,
+if we invoke C<Animal-E<gt>speak> there, the first parameter to the
+method will be C<"Animal"> not C<"Mouse">, and when time comes for it
+to call for the C<sound>, it won't have the right class to come back
+to this package.
+
+Invoking C<Animal::speak> directly is a mess, however.  What if
+C<Animal::speak> didn't exist before, and was being inherited from a
+class mentioned in C<@Animal::ISA>?  Because we are no longer using
+the method arrow, we get one and only one chance to hit the right
+subroutine.
+
+Also note that the C<Animal> classname is now hardwired into the
+subroutine selection.  This is a mess if someone maintains the code,
+changing C<@ISA> for <Mouse> and didn't notice C<Animal> there in
+C<speak>.  So, this is probably not the right way to go.
+
+=head2 Starting the search from a different place
+
+A better solution is to tell Perl to search from a higher place
+in the inheritance chain:
+
+    # same Animal as before
+    { package Mouse;
+      # same @ISA, &sound as before
+      sub speak {
+        my $class = shift;
+        $class->Animal::speak;
+        print "[but you can barely hear it!]\n";
+      }
+    }
+
+Ahh.  This works.  Using this syntax, we start with C<Animal> to find
+C<speak>, and use all of C<Animal>'s inheritance chain if not found
+immediately.  And yet the first parameter will be C<$class>, so the
+found C<speak> method will get C<Mouse> as its first entry, and
+eventually work its way back to C<Mouse::sound> for the details.
+
+But this isn't the best solution.  We still have to keep the C<@ISA>
+and the initial search package coordinated.  Worse, if C<Mouse> had
+multiple entries in C<@ISA>, we wouldn't necessarily know which one
+had actually defined C<speak>.  So, is there an even better way?
+
+=head2 The SUPER way of doing things
+
+By changing the C<Animal> class to the C<SUPER> class in that
+invocation, we get a search of all of our super classes (classes
+listed in C<@ISA>) automatically:
+
+    # same Animal as before
+    { package Mouse;
+      # same @ISA, &sound as before
+      sub speak {
+        my $class = shift;
+        $class->SUPER::speak;
+        print "[but you can barely hear it!]\n";
+      }
+    }
+
+So, C<SUPER::speak> means look in the current package's C<@ISA> for
+C<speak>, invoking the first one found.
+
+=head2 Where we're at so far...
+
+So far, we've seen the method arrow syntax:
+
+  Class->method(@args);
+
+or the equivalent:
+
+  $a = "Class";
+  $a->method(@args);
+
+which constructs an argument list of:
+
+  ("Class", @args)
+
+and attempts to invoke
+
+  Class::method("Class", @Args);
+
+However, if C<Class::method> is not found, then C<@Class::ISA> is examined
+(recursively) to locate a package that does indeed contain C<method>,
+and that subroutine is invoked instead.
+
+Using this simple syntax, we have class methods, (multiple)
+inheritance, overriding, and extending.  Using just what we've seen so
+far, we've been able to factor out common code, and provide a nice way
+to reuse implementations with variations.  This is at the core of what
+objects provide, but objects also provide instance data, which we
+haven't even begun to cover.
+
+=head2 A horse is a horse, of course of course -- or is it?
+
+Let's start with the code for the C<Animal> class
+and the C<Horse> class:
+
+  { package Animal;
+    sub speak {
+      my $class = shift;
+      print "a $class goes ", $class->sound, "!\n"
+    }
+  }
+  { package Horse;
+    @ISA = qw(Animal);
+    sub sound { "neigh" }
+  }
+
+This lets us invoke C<Horse-E<gt>speak> to ripple upward to
+C<Animal::speak>, calling back to C<Horse::sound> to get the specific
+sound, and the output of:
+
+  a Horse goes neigh!
+
+But all of our Horse objects would have to be absolutely identical.
+If I add a subroutine, all horses automatically share it.  That's
+great for making horses the same, but how do we capture the
+distinctions about an individual horse?  For example, suppose I want
+to give my first horse a name.  There's got to be a way to keep its
+name separate from the other horses.
+
+We can do that by drawing a new distinction, called an "instance".
+An "instance" is generally created by a class.  In Perl, any reference
+can be an instance, so let's start with the simplest reference
+that can hold a horse's name: a scalar reference.
+
+  my $name = "Mr. Ed";
+  my $talking = \$name;
+
+So now C<$talking> is a reference to what will be the instance-specific
+data (the name).  The final step in turning this into a real instance
+is with a special operator called C<bless>:
+
+  bless $talking, Horse;
+
+This operator stores information about the package named C<Horse> into
+the thing pointed at by the reference.  At this point, we say
+C<$talking> is an instance of C<Horse>.  That is, it's a specific
+horse.  The reference is otherwise unchanged, and can still be used
+with traditional dereferencing operators.
+
+=head2 Invoking an instance method
+
+The method arrow can be used on instances, as well as names of
+packages (classes).  So, let's get the sound that C<$talking> makes:
+
+  my $noise = $talking->sound;
+
+To invoke C<sound>, Perl first notes that C<$talking> is a blessed
+reference (and thus an instance).  It then constructs an argument
+list, in this case from just C<($talking)>.  (Later we'll see that
+arguments will take their place following the instance variable,
+just like with classes.)
+
+Now for the fun part: Perl takes the class in which the instance was
+blessed, in this case C<Horse>, and uses that to locate the subroutine
+to invoke the method.  In this case, C<Horse::sound> is found directly
+(without using inheritance), yielding the final subroutine invocation:
+
+  Horse::sound($talking)
+
+Note that the first parameter here is still the instance, not the name
+of the class as before.  We'll get C<neigh> as the return value, and
+that'll end up as the C<$noise> variable above.
+
+If Horse::sound had not been found, we'd be wandering up the
+C<@Horse::ISA> list to try to find the method in one of the
+superclasses, just as for a class method.  The only difference between
+a class method and an instance method is whether the first parameter
+is a instance (a blessed reference) or a class name (a string).
+
+=head2 Accessing the instance data
+
+Because we get the instance as the first parameter, we can now access
+the instance-specific data.  In this case, let's add a way to get at
+the name:
+
+  { package Horse;
+    @ISA = qw(Animal);
+    sub sound { "neigh" }
+    sub name {
+      my $self = shift;
+      $$self;
+    }
+  }
+    
+Now we call for the name:
+
+  print $talking->name, " says ", $talking->sound, "\n";
+
+Inside C<Horse::name>, the C<@_> array contains just C<$talking>,
+which the C<shift> stores into C<$self>.  (It's traditional to shift
+the first parameter off into a variable named C<$self> for instance
+methods, so stay with that unless you have strong reasons otherwise.)
+Then, C<$self> gets de-referenced as a scalar ref, yielding C<Mr. Ed>,
+and we're done with that.  The result is:
+
+  Mr. Ed says neigh.
+
+=head2 How to build a horse
+
+Of course, if we constructed all of our horses by hand, we'd most
+likely make mistakes from time to time.  We're also violating one of
+the properties of object-oriented programming, in that the "inside
+guts" of a Horse are visible.  That's good if you're a veterinarian,
+but not if you just like to own horses.  So, let's let the Horse class
+build a new horse:
+
+  { package Horse;
+    @ISA = qw(Animal);
+    sub sound { "neigh" }
+    sub name {
+      my $self = shift;
+      $$self;
+    }
+    sub named {
+      my $class = shift;
+      my $name = shift;
+      bless \$name, $class;
+    }
+  }
+
+Now with the new C<named> method, we can build a horse:
+
+  my $talking = Horse->named("Mr. Ed");
+
+Notice we're back to a class method, so the two arguments to
+C<Horse::named> are C<Horse> and C<Mr. Ed>.  The C<bless> operator
+not only blesses C<$name>, it also returns the reference to C<$name>,
+so that's fine as a return value.  And that's how to build a horse.
+
+=head2 Inheriting the constructor
+
+But was there anything specific to C<Horse> in that method?  No.  Therefore,
+it's also the same recipe for building anything else that inherited from
+C<Animal>, so let's put it there:
+
+  { package Animal;
+    sub speak {
+      my $class = shift;
+      print "a $class goes ", $class->sound, "!\n"
+    }
+    sub name {
+      my $self = shift;
+      $$self;
+    }
+    sub named {
+      my $class = shift;
+      my $name = shift;
+      bless \$name, $class;
+    }
+  }
+  { package Horse;
+    @ISA = qw(Animal);
+    sub sound { "neigh" }
+  }
+
+Ahh, but what happens if we invoke C<speak> on an instance?
+
+  my $talking = Horse->named("Mr. Ed");
+  $talking->speak;
+
+We get a debugging value:
+
+  a Horse=SCALAR(0xaca42ac) goes neigh!
+
+Why?  Because the C<Animal::speak> routine is expecting a classname as
+its first parameter, not an instance.  When the instance is passed in,
+we'll end up using a blessed scalar reference as a string, and that
+shows up as we saw it just now.
+
+=head2 Making a method work with either classes or instances
+
+All we need is for a method to detect if it is being called on a class
+or called on an instance.  The most straightforward way is with the
+C<ref> operator.  This returns a string (the classname) when used on a
+blessed reference, and C<undef> when used on a string (like a
+classname).  Let's modify the C<name> method first to notice the change:
+
+  sub name {
+    my $either = shift;
+    ref $either
+      ? $$either # it's an instance, return name
+      : "an unnamed $either"; # it's a class, return generic
+  }
+
+Here, the C<?:> operator comes in handy to select either the
+dereference or a derived string.  Now we can use this with either an
+instance or a class.  Note that I've changed the first parameter
+holder to C<$either> to show that this is intended:
+
+  my $talking = Horse->named("Mr. Ed");
+  print Horse->name, "\n"; # prints "an unnamed Horse\n"
+  print $talking->name, "\n"; # prints "Mr Ed.\n"
+
+and now we'll fix C<speak> to use this:
+
+  sub speak {
+    my $either = shift;
+    print $either->name, " goes ", $either->sound, "\n";
+  }
+
+And since C<sound> already worked with either a class or an instance,
+we're done!
+
+=head2 Adding parameters to a method
+
+Let's train our animals to eat:
+
+  { package Animal;
+    sub named {
+      my $class = shift;
+      my $name = shift;
+      bless \$name, $class;
+    }
+    sub name {
+      my $either = shift;
+      ref $either
+	? $$either # it's an instance, return name
+	: "an unnamed $either"; # it's a class, return generic
+    }
+    sub speak {
+      my $either = shift;
+      print $either->name, " goes ", $either->sound, "\n";
+    }
+    sub eat {
+      my $either = shift;
+      my $food = shift;
+      print $either->name, " eats $food.\n";
+    }
+  }
+  { package Horse;
+    @ISA = qw(Animal);
+    sub sound { "neigh" }
+  }
+  { package Sheep;
+    @ISA = qw(Animal);
+    sub sound { "baaaah" }
+  }
+
+And now try it out:
+
+  my $talking = Horse->named("Mr. Ed");
+  $talking->eat("hay");
+  Sheep->eat("grass");
+
+which prints:
+
+  Mr. Ed eats hay.
+  an unnamed Sheep eats grass.
+
+An instance method with parameters gets invoked with the instance,
+and then the list of parameters.  So that first invocation is like:
+
+  Animal::eat($talking, "hay");
+
+=head2 More interesting instances
+
+What if an instance needs more data?  Most interesting instances are
+made of many items, each of which can in turn be a reference or even
+another object.  The easiest way to store these is often in a hash.
+The keys of the hash serve as the names of parts of the object (often
+called "instance variables" or "member variables"), and the
+corresponding values are, well, the values.
+
+But how do we turn the horse into a hash?  Recall that an object was
+any blessed reference.  We can just as easily make it a blessed hash
+reference as a blessed scalar reference, as long as everything that
+looks at the reference is changed accordingly.
+
+Let's make a sheep that has a name and a color:
+
+  my $bad = bless { Name => "Evil", Color => "black" }, Sheep;
+
+so C<$bad-E<gt>{Name}> has C<Evil>, and C<$bad-E<gt>{Color}> has
+C<black>.  But we want to make C<$bad-E<gt>name> access the name, and
+that's now messed up because it's expecting a scalar reference.  Not
+to worry, because that's pretty easy to fix up:
+
+  ## in Animal
+  sub name {
+    my $either = shift;
+    ref $either ?
+      $either->{Name} :
+      "an unnamed $either";
+  }
+
+And of course C<named> still builds a scalar sheep, so let's fix that
+as well:
+
+  ## in Animal
+  sub named {
+    my $class = shift;
+    my $name = shift;
+    my $self = { Name => $name, Color => $class->default_color };
+    bless $self, $class;
+  }
+
+What's this C<default_color>?  Well, if C<named> has only the name,
+we still need to set a color, so we'll have a class-specific initial color.
+For a sheep, we might define it as white:
+
+  ## in Sheep
+  sub default_color { "white" }
+
+And then to keep from having to define one for each additional class,
+we'll define a "backstop" method that serves as the "default default",
+directly in C<Animal>:
+
+  ## in Animal
+  sub default_color { "brown" }
+
+Now, because C<name> and C<named> were the only methods that
+referenced the "structure" of the object, the rest of the methods can
+remain the same, so C<speak> still works as before.
+
+=head2 A horse of a different color
+
+But having all our horses be brown would be boring.  So let's add a
+method or two to get and set the color.
+
+  ## in Animal
+  sub color {
+    $_[0]->{Color}
+  }
+  sub set_color {
+    $_[0]->{Color} = $_[1];
+  }
+
+Note the alternate way of accessing the arguments: C<$_[0]> is used
+in-place, rather than with a C<shift>.  (This saves us a bit of time
+for something that may be invoked frequently.)  And now we can fix
+that color for Mr. Ed:
+
+  my $talking = Horse->named("Mr. Ed");
+  $talking->set_color("black-and-white");
+  print $talking->name, " is colored ", $talking->color, "\n";
+
+which results in:
+
+  Mr. Ed is colored black-and-white
+
+=head2 Summary
+
+So, now we have class methods, constructors, instance methods,
+instance data, and even accessors.  But that's still just the
+beginning of what Perl has to offer.  We haven't even begun to talk
+about accessors that double as getters and setters, destructors,
+indirect object notation, subclasses that add instance data, per-class
+data, overloading, "isa" and "can" tests, C<UNIVERSAL> class, and so
+on.  That's for the rest of the Perl documentation to cover.
+Hopefully, this gets you started, though.
+
+=head1 SEE ALSO
+
+For more information, see L<perlobj> (for all the gritty details about
+Perl objects, now that you've seen the basics), L<perltoot> (the
+tutorial for those who already know objects), L<perlbot> (for some
+more tricks), and books such as Damian Conway's excellent I<Object
+Oriented Perl>.
+
+=head1 COPYRIGHT
+
+Copyright (c) 1999, 2000 by Randal L. Schwartz and Stonehenge
+Consulting Services, Inc.  Permission is hereby granted to distribute
+this document intact with the Perl distribution, and in accordance
+with the licenses of the Perl distribution; derived documents must
+include this copyright notice intact.
+
+Portions of this text have been derived from Perl Training materials
+originally appearing in the I<Packages, References, Objects, and
+Modules> course taught by instructors for Stonehenge Consulting
+Services, Inc. and used with permission.
+
+Portions of this text have been derived from materials originally
+appearing in I<Linux Magazine> and used with permission.
diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index 0465b451b4..205365eb53 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -1840,6 +1840,10 @@ A tutorial on using open() effectively.
 
 A tutorial that introduces the essentials of references.
 
+=item perlboot.pod
+
+A tutorial for beginners on object-oriented Perl.
+
 =item perltootc.pod
 
 A tutorial on managing class data for object modules.
diff --git a/pod/perltoc.pod b/pod/perltoc.pod
index a7c1b624bf..bc45dd88ad 100644
--- a/pod/perltoc.pod
+++ b/pod/perltoc.pod
@@ -1145,15 +1145,20 @@ CGI script to do bad things?
 
 =item Perl Source Incompatibilities
 
-CHECK is a new keyword, Treatment of list slices of undef has changed,
-Possibly changed pseudo-random number generator, Hashing function for hash
-keys has changed, C<undef> fails on read only values, Close-on-exec bit may
-be set on pipe() handles, Writing C<"$$1"> to mean C<"${$}1"> is
-unsupported, delete(), values() and C<\(%h)> operate on aliases to values,
-not copies, vec(EXPR,OFFSET,BITS) enforces powers-of-two BITS, Text of some
-diagnostic output has changed, C<%@> has been removed, Parenthesized not()
-behaves like a list operator, Semantics of bareword prototype C<(*)> have
-changed
+CHECK is a new keyword, Treatment of list slices of undef has changed
+
+=item Perl's version numbering has changed
+
+Literals of the form C<1.2.3> parse differently, Possibly changed
+pseudo-random number generator, Hashing function for hash keys has changed,
+C<undef> fails on read only values, Close-on-exec bit may be set on pipe
+and socket handles, Writing C<"$$1"> to mean C<"${$}1"> is unsupported,
+delete(), values() and C<\(%h)> operate on aliases to values, not copies,
+vec(EXPR,OFFSET,BITS) enforces powers-of-two BITS, Text of some diagnostic
+output has changed, C<%@> has been removed, Parenthesized not() behaves
+like a list operator, Semantics of bareword prototype C<(*)> have changed
+
+=item On 64-bit platforms the semantics of bit operators have changed
 
 =item C Source Incompatibilities
 
@@ -1171,9 +1176,11 @@ C<PATCHLEVEL> is now C<PERL_VERSION>, Support for C++ exceptions
 
 =over
 
+=item -Dusethreads means something different
+
 =item New Configure flags
 
-=item -Dusethreads and -Duse64bits now more daring
+=item Threadedness and 64-bitness now more daring
 
 =item Long Doubles
 
@@ -1197,7 +1204,7 @@ C<PATCHLEVEL> is now C<PERL_VERSION>, Support for C++ exceptions
 
 =item Unicode and UTF-8 support
 
-=item Interpreter threads
+=item Interpreter cloning, threads, and concurrency
 
 =item Lexically scoped warning categories
 
@@ -1205,6 +1212,8 @@ C<PATCHLEVEL> is now C<PERL_VERSION>, Support for C++ exceptions
 
 =item "our" declarations
 
+=item Support for strings represented as a vector of ordinals
+
 =item Weak references
 
 =item File globbing implemented internally
@@ -1263,6 +1272,8 @@ C<PATCHLEVEL> is now C<PERL_VERSION>, Support for C++ exceptions
 
 =item New variable $^C reflects C<-c> switch
 
+=item New variable $^V contains Perl version in v5.6.0 format
+
 =item Optional Y2K warnings
 
 =back
@@ -1366,11 +1377,13 @@ C<PATCHLEVEL> is now C<PERL_VERSION>, Support for C++ exceptions
 =item Modules
 
 attributes, B, ByteLoader, constant, charnames, Data::Dumper, DB, DB_File,
-Devel::DProf, Dumpvalue, Benchmark, Devel::Peek, ExtUtils::MakeMaker,
-Fcntl, File::Compare, File::Find, File::Glob, File::Spec,
-File::Spec::Functions, Getopt::Long, IO, JPL, lib, Math::BigInt,
-Math::Complex, Math::Trig, Pod::Parser, Pod::Text and Pod::Man, SDBM_File,
-Time::Local, Win32, DBM Filters
+Devel::DProf, Dumpvalue, Benchmark, Devel::Peek, English,
+ExtUtils::MakeMaker, Fcntl, File::Compare, File::Find, File::Glob,
+File::Spec, File::Spec::Functions, Getopt::Long, IO, JPL, lib,
+Math::BigInt, Math::Complex, Math::Trig, Pod::Parser, Pod::InputObjects,
+Pod::Checker, podchecker, Pod::ParseUtils, Pod::Find, Pod::Select,
+podselect, Pod::Usage, pod2usage, Pod::Text and Pod::Man, SDBM_File,
+Sys::Syslog, Sys::Hostname, Time::Local, Win32, DBM Filters
 
 =item Pragmata
 
@@ -1391,7 +1404,8 @@ Time::Local, Win32, DBM Filters
 =item Documentation Changes
 
 perlapi.pod, perlcompile.pod, perlfilter.pod, perlhack.pod, perlintern.pod,
-perlopentut.pod, perlreftut.pod, perltootc.pod
+perlopentut.pod, perlreftut.pod, perlboot.pod, perltootc.pod,
+perlunicode.pod
 
 =item New or Changed Diagnostics
 
@@ -1405,32 +1419,32 @@ early to check prototype, %s argument is not a HASH or ARRAY element, %s
 argument is not a HASH or ARRAY element or slice, %s argument is not a
 subroutine name, %s package attribute may clash with future reserved word:
 %s,	    (in cleanup) %s, <> should be quotes, Attempt to join self, Bad
-evalled substitution pattern, Bad realloc() ignored, Binary number >
-0b11111111111111111111111111111111 non-portable, Bit vector size > 32
-non-portable, Buffer overflow in prime_env_iter: %s, Can't check filesystem
-of script "%s", Can't declare class for non-scalar %s in "%s", Can't
-declare %s in "%s", Can't ignore signal CHLD, forcing to default, Can't
-modify non-lvalue subroutine call, Can't read CRTL environ, Can't remove
-%s: %s, skipping file, Can't return %s from lvalue subroutine, Can't weaken
-a nonreference, Character class [:%s:] unknown, Character class syntax [%s]
-belongs inside character classes, Constant is not %s reference,
-constant(%s): %%^H is not localized, constant(%s): %s, defined(@array) is
-deprecated, defined(%hash) is deprecated, Did not produce a valid header,
-Did you mean "local" instead of "our"?, Document contains no data, entering
-effective %s failed, false [] range "%s" in regexp, Filehandle %s opened
-only for output, flock() on closed filehandle %s, Global symbol "%s"
-requires explicit package name, Hexadecimal number > 0xffffffff
-non-portable, Ill-formed CRTL environ value "%s", Ill-formed message in
-prime_env_iter: |%s|, Illegal binary digit %s, Illegal binary digit %s
-ignored, Illegal number of bits in vec, Integer overflow in %s number,
-Invalid %s attribute: %s, Invalid %s attributes: %s, invalid [] range "%s"
-in regexp, Invalid separator character %s in attribute list, Invalid
-separator character %s in subroutine attribute list, leaving effective %s
-failed, Lvalue subs returning %s not implemented yet, Method %s not
-permitted, Missing %sbrace%s on \N{}, Missing command in piped open,
-Missing name in "my sub", No %s specified for -%c, No package name allowed
-for variable %s in "our", No space allowed after -%c, no UTC offset
-information; assuming local time is UTC, Octal number > 037777777777
+evalled substitution pattern, Bad realloc() ignored, Bareword found in
+conditional, Binary number > 0b11111111111111111111111111111111
+non-portable, Bit vector size > 32 non-portable, Buffer overflow in
+prime_env_iter: %s, Can't check filesystem of script "%s", Can't declare
+class for non-scalar %s in "%s", Can't declare %s in "%s", Can't ignore
+signal CHLD, forcing to default, Can't modify non-lvalue subroutine call,
+Can't read CRTL environ, Can't remove %s: %s, skipping file, Can't return
+%s from lvalue subroutine, Can't weaken a nonreference, Character class
+[:%s:] unknown, Character class syntax [%s] belongs inside character
+classes, Constant is not %s reference, constant(%s): %%^H is not localized,
+constant(%s): %s, defined(@array) is deprecated, defined(%hash) is
+deprecated, Did not produce a valid header, Did you mean "local" instead of
+"our"?, Document contains no data, entering effective %s failed, false []
+range "%s" in regexp, Filehandle %s opened only for output, flock() on
+closed filehandle %s, Global symbol "%s" requires explicit package name,
+Hexadecimal number > 0xffffffff non-portable, Ill-formed CRTL environ value
+"%s", Ill-formed message in prime_env_iter: |%s|, Illegal binary digit %s,
+Illegal binary digit %s ignored, Illegal number of bits in vec, Integer
+overflow in %s number, Invalid %s attribute: %s, Invalid %s attributes: %s,
+invalid [] range "%s" in regexp, Invalid separator character %s in
+attribute list, Invalid separator character %s in subroutine attribute
+list, leaving effective %s failed, Lvalue subs returning %s not implemented
+yet, Method %s not permitted, Missing %sbrace%s on \N{}, Missing command in
+piped open, Missing name in "my sub", No %s specified for -%c, No package
+name allowed for variable %s in "our", No space allowed after -%c, no UTC
+offset information; assuming local time is UTC, Octal number > 037777777777
 non-portable, panic: del_backref, panic: kid popen errno read, panic:
 magic_killbackrefs, Parentheses missing around "%s" list, Possible Y2K bug:
 %s, Premature end of script headers, Repeat count in pack overflows, Repeat
@@ -1448,8 +1462,8 @@ number must be a constant number
 =item Obsolete Diagnostics
 
 Character class syntax [: :] is reserved for future extensions, Ill-formed
-logical name |%s| in prime_env_iter, regexp too big, Use of "$$<digit>" to
-mean "${$}<digit>" is deprecated
+logical name |%s| in prime_env_iter, Probable precedence problem on %s,
+regexp too big, Use of "$$<digit>" to mean "${$}<digit>" is deprecated
 
 =item BUGS
 
@@ -1604,6 +1618,8 @@ regular expressions
 
 =item Bitwise String Operators
 
+=item Strings of Character
+
 =item Integer Arithmetic
 
 =item Floating-point Arithmetic
@@ -1678,9 +1694,9 @@ OS/2, MS-DOS, Win95/NT, Macintosh, VMS
 
 =item Command Switches
 
-B<-0>[I<digits>], B<-a>, B<-c>, B<-d>, B<-d:>I<foo>, B<-D>I<letters>,
-B<-D>I<number>, B<-e> I<commandline>, B<-F>I<pattern>, B<-h>,
-B<-i>[I<extension>], B<-I>I<directory>, B<-l>[I<octnum>],
+B<-0>[I<digits>], B<-a>, B<-C>, B<-c>, B<-d>, B<-d:>I<foo>,
+B<-D>I<letters>, B<-D>I<number>, B<-e> I<commandline>, B<-F>I<pattern>,
+B<-h>, B<-i>[I<extension>], B<-I>I<directory>, B<-l>[I<octnum>],
 B<-m>[B<->]I<module>, B<-M>[B<->]I<module>, B<-M>[B<->]I<'module ...'>,
 B<-[mM]>[B<->]I<module=arg[,arg]...>, B<-n>, B<-p>, B<-P>, B<-s>, B<-S>,
 B<-T>, B<-u>, B<-U>, B<-v>, B<-V>, B<-V:>I<name>, B<-w>, B<-W>, B<-X>,
@@ -1749,20 +1765,21 @@ FILEHANDLE,FUNCTION,SCALAR, join EXPR,LIST, keys HASH, kill SIGNAL, LIST,
 last LABEL, last, lc EXPR, lc, lcfirst EXPR, lcfirst, length EXPR, length,
 link OLDFILE,NEWFILE, listen SOCKET,QUEUESIZE, local EXPR, localtime EXPR,
 lock, log EXPR, log, lstat FILEHANDLE, lstat EXPR, lstat, m//, map BLOCK
-LIST, map EXPR,LIST, mkdir FILENAME,MASK, msgctl ID,CMD,ARG, msgget
-KEY,FLAGS, msgsnd ID,MSG,FLAGS, msgrcv ID,VAR,SIZE,TYPE,FLAGS, my EXPR, my
-EXPR : ATTRIBUTES, next LABEL, next, no Module LIST, oct EXPR, oct, open
-FILEHANDLE,MODE,EXPR, open FILEHANDLE,EXPR, open FILEHANDLE, opendir
-DIRHANDLE,EXPR, ord EXPR, ord, our EXPR, pack TEMPLATE,LIST, package,
-package NAMESPACE, pipe READHANDLE,WRITEHANDLE, pop ARRAY, pop, pos SCALAR,
-pos, print FILEHANDLE LIST, print LIST, print, printf FILEHANDLE FORMAT,
-LIST, printf FORMAT, LIST, prototype FUNCTION, push ARRAY,LIST, q/STRING/,
-qq/STRING/, qr/STRING/, qx/STRING/, qw/STRING/, quotemeta EXPR, quotemeta,
-rand EXPR, rand, read FILEHANDLE,SCALAR,LENGTH,OFFSET, read
-FILEHANDLE,SCALAR,LENGTH, readdir DIRHANDLE, readline EXPR, readlink EXPR,
-readlink, readpipe EXPR, recv SOCKET,SCALAR,LENGTH,FLAGS, redo LABEL, redo,
-ref EXPR, ref, rename OLDNAME,NEWNAME, require EXPR, require, reset EXPR,
-reset, return EXPR, return, reverse LIST, rewinddir DIRHANDLE, rindex
+LIST, map EXPR,LIST, mkdir FILENAME,MASK, mkdir FILENAME, msgctl
+ID,CMD,ARG, msgget KEY,FLAGS, msgsnd ID,MSG,FLAGS, msgrcv
+ID,VAR,SIZE,TYPE,FLAGS, my EXPR, my EXPR : ATTRIBUTES, next LABEL, next, no
+Module LIST, oct EXPR, oct, open FILEHANDLE,MODE,EXPR, open
+FILEHANDLE,EXPR, open FILEHANDLE, opendir DIRHANDLE,EXPR, ord EXPR, ord,
+our EXPR, pack TEMPLATE,LIST, package, package NAMESPACE, pipe
+READHANDLE,WRITEHANDLE, pop ARRAY, pop, pos SCALAR, pos, print FILEHANDLE
+LIST, print LIST, print, printf FILEHANDLE FORMAT, LIST, printf FORMAT,
+LIST, prototype FUNCTION, push ARRAY,LIST, q/STRING/, qq/STRING/,
+qr/STRING/, qx/STRING/, qw/STRING/, quotemeta EXPR, quotemeta, rand EXPR,
+rand, read FILEHANDLE,SCALAR,LENGTH,OFFSET, read FILEHANDLE,SCALAR,LENGTH,
+readdir DIRHANDLE, readline EXPR, readlink EXPR, readlink, readpipe EXPR,
+recv SOCKET,SCALAR,LENGTH,FLAGS, redo LABEL, redo, ref EXPR, ref, rename
+OLDNAME,NEWNAME, require VERSION, require EXPR, require, reset EXPR, reset,
+return EXPR, return, reverse LIST, rewinddir DIRHANDLE, rindex
 STR,SUBSTR,POSITION, rindex STR,SUBSTR, rmdir FILENAME, rmdir, s///, scalar
 EXPR, seek FILEHANDLE,POSITION,WHENCE, seekdir DIRHANDLE,POS, select
 FILEHANDLE, select, select RBITS,WBITS,EBITS,TIMEOUT, semctl
@@ -1774,23 +1791,24 @@ shmwrite ID,STRING,POS,SIZE, shutdown SOCKET,HOW, sin EXPR, sin, sleep
 EXPR, sleep, socket SOCKET,DOMAIN,TYPE,PROTOCOL, socketpair
 SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL, sort SUBNAME LIST, sort BLOCK LIST,
 sort LIST, splice ARRAY,OFFSET,LENGTH,LIST, splice ARRAY,OFFSET,LENGTH,
-splice ARRAY,OFFSET, split /PATTERN/,EXPR,LIMIT, split /PATTERN/,EXPR,
-split /PATTERN/, split, sprintf FORMAT, LIST, sqrt EXPR, sqrt, srand EXPR,
-srand, stat FILEHANDLE, stat EXPR, stat, study SCALAR, study, sub BLOCK,
-sub NAME, sub NAME BLOCK, substr EXPR,OFFSET,LENGTH,REPLACEMENT, substr
-EXPR,OFFSET,LENGTH, substr EXPR,OFFSET, symlink OLDFILE,NEWFILE, syscall
-LIST, sysopen FILEHANDLE,FILENAME,MODE, sysopen
-FILEHANDLE,FILENAME,MODE,PERMS, sysread FILEHANDLE,SCALAR,LENGTH,OFFSET,
-sysread FILEHANDLE,SCALAR,LENGTH, sysseek FILEHANDLE,POSITION,WHENCE,
-system LIST, system PROGRAM LIST, syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET,
-syswrite FILEHANDLE,SCALAR,LENGTH, syswrite FILEHANDLE,SCALAR, tell
-FILEHANDLE, tell, telldir DIRHANDLE, tie VARIABLE,CLASSNAME,LIST, tied
-VARIABLE, time, times, tr///, truncate FILEHANDLE,LENGTH, truncate
-EXPR,LENGTH, uc EXPR, uc, ucfirst EXPR, ucfirst, umask EXPR, umask, undef
-EXPR, undef, unlink LIST, unlink, unpack TEMPLATE,EXPR, untie VARIABLE,
-unshift ARRAY,LIST, use Module LIST, use Module, use Module VERSION LIST,
-use VERSION, utime LIST, values HASH, vec EXPR,OFFSET,BITS, wait, waitpid
-PID,FLAGS, wantarray, warn LIST, write FILEHANDLE, write EXPR, write, y///
+splice ARRAY,OFFSET, splice ARRAY, split /PATTERN/,EXPR,LIMIT, split
+/PATTERN/,EXPR, split /PATTERN/, split, sprintf FORMAT, LIST, sqrt EXPR,
+sqrt, srand EXPR, srand, stat FILEHANDLE, stat EXPR, stat, study SCALAR,
+study, sub BLOCK, sub NAME, sub NAME BLOCK, substr
+EXPR,OFFSET,LENGTH,REPLACEMENT, substr EXPR,OFFSET,LENGTH, substr
+EXPR,OFFSET, symlink OLDFILE,NEWFILE, syscall LIST, sysopen
+FILEHANDLE,FILENAME,MODE, sysopen FILEHANDLE,FILENAME,MODE,PERMS, sysread
+FILEHANDLE,SCALAR,LENGTH,OFFSET, sysread FILEHANDLE,SCALAR,LENGTH, sysseek
+FILEHANDLE,POSITION,WHENCE, system LIST, system PROGRAM LIST, syswrite
+FILEHANDLE,SCALAR,LENGTH,OFFSET, syswrite FILEHANDLE,SCALAR,LENGTH,
+syswrite FILEHANDLE,SCALAR, tell FILEHANDLE, tell, telldir DIRHANDLE, tie
+VARIABLE,CLASSNAME,LIST, tied VARIABLE, time, times, tr///, truncate
+FILEHANDLE,LENGTH, truncate EXPR,LENGTH, uc EXPR, uc, ucfirst EXPR,
+ucfirst, umask EXPR, umask, undef EXPR, undef, unlink LIST, unlink, unpack
+TEMPLATE,EXPR, untie VARIABLE, unshift ARRAY,LIST, use Module VERSION LIST,
+use Module VERSION, use Module LIST, use Module, use VERSION, utime LIST,
+values HASH, vec EXPR,OFFSET,BITS, wait, waitpid PID,FLAGS, wantarray, warn
+LIST, write FILEHANDLE, write EXPR, write, y///
 
 =back
 
@@ -1816,19 +1834,24 @@ $OUTPUT_RECORD_SEPARATOR, $ORS, $\, $LIST_SEPARATOR, $",
 $SUBSCRIPT_SEPARATOR, $SUBSEP, $;, $OFMT, $#, format_page_number HANDLE
 EXPR, $FORMAT_PAGE_NUMBER, $%, format_lines_per_page HANDLE EXPR,
 $FORMAT_LINES_PER_PAGE, $=, format_lines_left HANDLE EXPR,
-$FORMAT_LINES_LEFT, $-, @-, format_name HANDLE EXPR, $FORMAT_NAME, $~,
-format_top_name HANDLE EXPR, $FORMAT_TOP_NAME, $^,
-format_line_break_characters HANDLE EXPR, $FORMAT_LINE_BREAK_CHARACTERS,
-$:, format_formfeed HANDLE EXPR, $FORMAT_FORMFEED, $^L, $ACCUMULATOR, $^A,
-$CHILD_ERROR, $?, $OS_ERROR, $ERRNO, $!, $EXTENDED_OS_ERROR, $^E,
-$EVAL_ERROR, $@, $PROCESS_ID, $PID, $$, $REAL_USER_ID, $UID, $<,
-$EFFECTIVE_USER_ID, $EUID, $>, $REAL_GROUP_ID, $GID, $(,
-$EFFECTIVE_GROUP_ID, $EGID, $), $PROGRAM_NAME, $0, $[, $PERL_VERSION, $],
+$FORMAT_LINES_LEFT, $-, @-, C<$`> is the same as C<substr($var, 0, $-[0]>),
+C<$&> is the same as C<substr($var, $-[0], $+[0] - $-[0]>), C<$'> is the
+same as C<substr($var, $+[0]>), C<$1> is the same as C<substr($var, $-[1],
+$+[1] - $-[1])>, C<$2> is the same as C<substr($var, $-[2], $+[2] -
+$-[2])>, C<$3> is the same as C<substr $var, $-[3], $+[3] - $-[3]>),
+format_name HANDLE EXPR, $FORMAT_NAME, $~, format_top_name HANDLE EXPR,
+$FORMAT_TOP_NAME, $^, format_line_break_characters HANDLE EXPR,
+$FORMAT_LINE_BREAK_CHARACTERS, $:, format_formfeed HANDLE EXPR,
+$FORMAT_FORMFEED, $^L, $ACCUMULATOR, $^A, $CHILD_ERROR, $?, $OS_ERROR,
+$ERRNO, $!, $EXTENDED_OS_ERROR, $^E, $EVAL_ERROR, $@, $PROCESS_ID, $PID,
+$$, $REAL_USER_ID, $UID, $<, $EFFECTIVE_USER_ID, $EUID, $>, $REAL_GROUP_ID,
+$GID, $(, $EFFECTIVE_GROUP_ID, $EGID, $), $PROGRAM_NAME, $0, $[, $],
 $COMPILING, $^C, $DEBUGGING, $^D, $SYSTEM_FD_MAX, $^F, $^H, %^H,
 $INPLACE_EDIT, $^I, $^M, $OSNAME, $^O, $PERLDB, $^P, 0x01, 0x02, 0x04,
-0x08, 0x10, 0x20, $^R, $^S, $BASETIME, $^T, $WARNING, $^W, ${^WARNING_BITS},
-$EXECUTABLE_NAME, $^X, $ARGV, @ARGV, @INC, @_, %INC, %ENV, $ENV{expr},
-%SIG, $SIG{expr}
+0x08, 0x10, 0x20, 0x40, 0x80, 0x100, 0x200, $LAST_REGEXP_CODE_RESULT, $^R,
+$EXCEPTIONS_BEING_CAUGHT, $^S, $BASETIME, $^T, $PERL_VERSION, $^V,
+$WARNING, $^W, ${^WARNING_BITS}, ${^WIDE_SYSTEM_CALLS}, $EXECUTABLE_NAME,
+$^X, $ARGV, @ARGV, @INC, @_, %INC, %ENV, $ENV{expr}, %SIG, $SIG{expr}
 
 =item Error Indicators
 
@@ -2385,6 +2408,64 @@ more elaborate constructs
 
 =back
 
+=head2 perlboot - Beginner's Object-Oriented Tutorial
+
+=over
+
+=item DESCRIPTION
+
+=over
+
+=item If we could talk to the animals...
+
+=item Introducing the method invocation arrow
+
+=item Invoking a barnyard
+
+=item The extra parameter of method invocation
+
+=item Calling a second method to simplify things
+
+=item Inheriting the windpipes
+
+=item A few notes about @ISA
+
+=item Overriding the methods
+
+=item Starting the search from a different place
+
+=item The SUPER way of doing things
+
+=item Where we're at so far...
+
+=item A horse is a horse, of course of course -- or is it?
+
+=item Invoking an instance method
+
+=item Accessing the instance data
+
+=item How to build a horse
+
+=item Inheriting the constructor
+
+=item Making a method work with either classes or instances
+
+=item Adding parameters to a method
+
+=item More interesting instances
+
+=item A horse of a different color
+
+=item Summary
+
+=back
+
+=item SEE ALSO
+
+=item COPYRIGHT
+
+=back
+
 =head2 perltoot - Tom's object-oriented tutorial for perl
 
 =over
@@ -3003,7 +3084,7 @@ portable
 =item CPAN Testers
 
 Mailing list: cpan-testers@perl.org, Testing results:
-C<http://testers.perl.org/>
+C<http://testers.cpan.org/>
 
 =item PLATFORMS
 
@@ -3019,8 +3100,8 @@ C<emx@iaehv.nl>,C<http://www.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/index.
 html> or
 C<ftp://hobbes.nmsu.edu/pub/os2/dev/emx>, Build instructions for Win32,
 L<perlwin32>, The ActiveState Pages, C<http://www.activestate.com/>, The
-Cygwin environment for Win32;
-L<README.cygwin>,C<http://sourceware.cygnus.com/cygwin/>, The U/WIN
+Cygwin environment for Win32; F<README.cygwin> (installed as
+L<perlcygwin>), C<http://sourceware.cygnus.com/cygwin/>, The U/WIN
 environment for Win32,C<http://www.research.att.com/sw/tools/uwin/>
 
 =item S<Mac OS>
@@ -3031,17 +3112,18 @@ C<http://pudge.net/mmp/>
 
 =item VMS
 
-L<README.vms>, L<perlvms.pod>, vmsperl list, C<majordomo@perl.org>, vmsperl
-on the web, C<http://www.sidhe.org/vmsperl/index.html>
+F<README.vms> (installed as L<README_vms>), L<perlvms>, vmsperl list,
+C<majordomo@perl.org>, vmsperl on the web,
+C<http://www.sidhe.org/vmsperl/index.html>
 
 =item VOS
 
-L<README.vos>, VOS mailing list, VOS Perl on the web at
+F<README.vos>, VOS mailing list, VOS Perl on the web at
 C<http://ftp.stratus.com/pub/vos/vos.html>
 
 =item EBCDIC Platforms
 
-L<README.os390>, L<README.posix-bc>, L<README.vmesa>, perl-mvs list, AS/400
+F<README.os390>, F<README.posix-bc>, F<README.vmesa>, perl-mvs list, AS/400
 Perl information at C<http://as400.rochester.ibm.com/>as well as on CPAN in
 the F<ports/> directory
 
@@ -3049,11 +3131,11 @@ the F<ports/> directory
 
 =item Other perls
 
-Amiga, L<README.amiga>, Atari, L<README.mint> and Guido Flohr's web
-pageC<http://stud.uni-sb.de/~gufl0000/>, Be OS, L<README.beos>, HP 300
-MPE/iX, L<README.mpeix> and Mark Bixby's web
+Amiga, F<README.amiga> (installed as L<perlamiga>), Atari, F<README.mint>
+and Guido Flohr's web pageC<http://stud.uni-sb.de/~gufl0000/>, Be OS,
+F<README.beos>, HP 300 MPE/iX, F<README.mpeix> and Mark Bixby's web
 pageC<http://www.cccd.edu/~markb/perlix.html>, Novell Netware, Plan 9,
-L<README.plan9>
+F<README.plan9>
 
 =back
 
@@ -3079,11 +3161,12 @@ FILEHANDLE, lstat EXPR, lstat, msgctl ID,CMD,ARG, msgget KEY,FLAGS, msgsnd
 ID,MSG,FLAGS, msgrcv ID,VAR,SIZE,TYPE,FLAGS, open FILEHANDLE,EXPR, open
 FILEHANDLE, pipe READHANDLE,WRITEHANDLE, readlink EXPR, readlink, select
 RBITS,WBITS,EBITS,TIMEOUT, semctl ID,SEMNUM,CMD,ARG, semget
-KEY,NSEMS,FLAGS, semop KEY,OPSTRING, setpgrp PID,PGRP, setpriority
-WHICH,WHO,PRIORITY, setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL, shmctl
-ID,CMD,ARG, shmget KEY,SIZE,FLAGS, shmread ID,VAR,POS,SIZE, shmwrite
-ID,STRING,POS,SIZE, socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL, stat
-FILEHANDLE, stat EXPR, stat, symlink OLDFILE,NEWFILE, syscall LIST, sysopen
+KEY,NSEMS,FLAGS, semop KEY,OPSTRING, setgrent, setpgrp PID,PGRP,
+setpriority WHICH,WHO,PRIORITY, setpwent, setsockopt
+SOCKET,LEVEL,OPTNAME,OPTVAL, shmctl ID,CMD,ARG, shmget KEY,SIZE,FLAGS,
+shmread ID,VAR,POS,SIZE, shmwrite ID,STRING,POS,SIZE, socketpair
+SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL, stat FILEHANDLE, stat EXPR, stat,
+symlink OLDFILE,NEWFILE, syscall LIST, sysopen
 FILEHANDLE,FILENAME,MODE,PERMS, system LIST, times, truncate
 FILEHANDLE,LENGTH, truncate EXPR,LENGTH, umask EXPR, umask, utime LIST,
 wait, waitpid PID,FLAGS
@@ -3092,11 +3175,11 @@ wait, waitpid PID,FLAGS
 
 =item CHANGES
 
-v1.45, 20 December 1999, v1.44, 19 July 1999, v1.43, 24 May 1999, v1.42, 22
-May 1999, v1.41, 19 May 1999, v1.40, 11 April 1999, v1.39, 11 February
-1999, v1.38, 31 December 1998, v1.37, 19 December 1998, v1.36, 9 September
-1998, v1.35, 13 August 1998, v1.33, 06 August 1998, v1.32, 05 August 1998,
-v1.30, 03 August 1998, v1.23, 10 July 1998
+v1.46, 12 February 2000, v1.45, 20 December 1999, v1.44, 19 July 1999,
+v1.43, 24 May 1999, v1.42, 22 May 1999, v1.41, 19 May 1999, v1.40, 11 April
+1999, v1.39, 11 February 1999, v1.38, 31 December 1998, v1.37, 19 December
+1998, v1.36, 9 September 1998, v1.35, 13 August 1998, v1.33, 06 August
+1998, v1.32, 05 August 1998, v1.30, 03 August 1998, v1.23, 10 July 1998
 
 =item AUTHORS / CONTRIBUTORS
 
@@ -3790,7 +3873,7 @@ method, locked
 
 =item Built-in Attributes
 
-locked, method
+locked, method, lvalue
 
 =item Available Subroutines
 
@@ -3878,8 +3961,8 @@ method, locked
 
 =back
 
-=head2 bytes - Perl pragma to turn force treating strings as bytes not
-UNICODE
+=head2 bytes - Perl pragma to force byte semantics rather than character
+semantics
 
 =over
 
@@ -3887,17 +3970,7 @@ UNICODE
 
 =item DESCRIPTION
 
-=back
-
-=head2 caller - inherit pragmatic attributes from the context of the caller
-
-=over
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-encoding
+=item SEE ALSO
 
 =back
 
@@ -3971,6 +4044,8 @@ diagnostics
 
 =item DESCRIPTION
 
+new, phash
+
 =item SEE ALSO
 
 =back
@@ -4224,7 +4299,7 @@ C<strict refs>, C<strict vars>, C<strict subs>
 
 =back
 
-=head2 utf8 - Perl pragma to turn on UTF-8 and Unicode support
+=head2 utf8 - Perl pragma to enable/disable UTF-8 in source code
 
 =over
 
@@ -4232,7 +4307,7 @@ C<strict refs>, C<strict vars>, C<strict subs>
 
 =item DESCRIPTION
 
-=item CAVEATS
+=item SEE ALSO
 
 =back
 
@@ -4254,6 +4329,8 @@ C<strict refs>, C<strict vars>, C<strict subs>
 
 =item DESCRIPTION
 
+warnings::enabled($category), warnings::warn($category, $message)
+
 =back
 
 =head1 MODULE DOCUMENTATION
@@ -4378,8 +4455,8 @@ USEFUL, PREVIOUS, RARE, TABLE
 
 =item B::GV METHODS
 
-NAME, STASH, SV, IO, FORM, AV, HV, EGV, CV, CVGEN, LINE, FILE, FILEGV,
-GvREFCNT, FLAGS
+is_empty, NAME, STASH, SV, IO, FORM, AV, HV, EGV, CV, CVGEN, LINE, FILE,
+FILEGV, GvREFCNT, FLAGS
 
 =item B::IO METHODS
 
@@ -4528,7 +4605,7 @@ B<-On>, B<-D>, B<-Do>, B<-Db>, B<-Da>, B<-DC>, B<-S>, B<-m>
 =item OPTIONS
 
 B<-ofilename>, B<-v>, B<-->, B<-uPackname>, B<-D>, B<-Do>, B<-Dc>, B<-DA>,
-B<-DC>, B<-DM>, B<-f>, B<-fcog>, B<-fno-cog>, B<-On>
+B<-DC>, B<-DM>, B<-f>, B<-fcog>, B<-fno-cog>, B<-On>, B<-llimit>
 
 =item EXAMPLES
 
@@ -5247,7 +5324,7 @@ B<name()>, B<value()>, B<domain()>, B<path()>, B<expires()>
 =item Interactive Mode
 
 Searching for authors, bundles, distribution files and modules, make, test,
-install, clean	modules or distributions, readme, look module or
+install, clean	modules or distributions, get, readme, look module or
 distribution, Signals
 
 =item CPAN::Shell
@@ -5280,10 +5357,10 @@ expand($type,@things), Programming Examples
 
 =item CONFIGURATION
 
-o conf E<lt>scalar optionE<gt>, o conf E<lt>scalar optionE<gt>
-E<lt>valueE<gt>, o conf E<lt>list optionE<gt>, o conf E<lt>list optionE<gt>
-[shift|pop], o conf E<lt>list optionE<gt> [unshift|push|splice]
-E<lt>listE<gt>
+C<o conf E<lt>scalar optionE<gt>>, C<o conf E<lt>scalar optionE<gt>
+E<lt>valueE<gt>>, C<o conf E<lt>list optionE<gt>>, C<o conf E<lt>list
+optionE<gt> [shift|pop]>, C<o conf E<lt>list optionE<gt>
+[unshift|push|splice] E<lt>listE<gt>>
 
 =over
 
@@ -5450,23 +5527,25 @@ C<d_endsent>, C<d_endspent>, C<d_eofnblk>, C<d_eunice>, C<d_fchmod>,
 C<d_fchown>, C<d_fcntl>, C<d_fd_macros>, C<d_fd_set>, C<d_fds_bits>,
 C<d_fgetpos>, C<d_flexfnam>, C<d_flock>, C<d_fork>, C<d_fpathconf>,
 C<d_fpos64_t>, C<d_fs_data_s>, C<d_fseeko>, C<d_fsetpos>, C<d_fstatfs>,
-C<d_fstatvfs>, C<d_ftello>, C<d_ftime>, C<d_Gconvert>, C<d_getgrent>,
-C<d_getgrps>, C<d_gethbyaddr>, C<d_gethbyname>, C<d_gethent>,
-C<d_gethname>, C<d_gethostprotos>, C<d_getlogin>, C<d_getmnt>,
-C<d_getmntent>, C<d_getnbyaddr>, C<d_getnbyname>, C<d_getnent>,
-C<d_getnetprotos>, C<d_getpbyname>, C<d_getpbynumber>, C<d_getpent>,
-C<d_getpgid>, C<d_getpgrp2>, C<d_getpgrp>, C<d_getppid>, C<d_getprior>,
-C<d_getprotoprotos>, C<d_getpwent>, C<d_getsbyname>, C<d_getsbyport>,
-C<d_getsent>, C<d_getservprotos>, C<d_getspent>, C<d_getspnam>,
-C<d_gettimeod>, C<d_gnulibc>, C<d_grpasswd>, C<d_hasmntopt>, C<d_htonl>,
-C<d_index>, C<d_inetaton>, C<d_int64t>, C<d_isascii>, C<d_killpg>,
-C<d_lchown>, C<d_ldbl_dig>, C<d_link>, C<d_locconv>, C<d_lockf>,
-C<d_longdbl>, C<d_longlong>, C<d_lstat>, C<d_mblen>, C<d_mbstowcs>,
-C<d_mbtowc>, C<d_memchr>, C<d_memcmp>, C<d_memcpy>, C<d_memmove>,
-C<d_memset>, C<d_mkdir>, C<d_mkfifo>, C<d_mktime>, C<d_msg>,
-C<d_msg_ctrunc>, C<d_msg_dontroute>, C<d_msg_oob>, C<d_msg_peek>,
-C<d_msg_proxy>, C<d_msgctl>, C<d_msgget>, C<d_msgrcv>, C<d_msgsnd>,
-C<d_mymalloc>, C<d_nice>, C<d_nvpresuv>, C<d_off64_t>,
+C<d_fstatvfs>, C<d_ftello>, C<d_ftime>, C<d_Gconvert>, C<d_getcwd>,
+C<d_getfsstat>, C<d_getgrent>, C<d_getgrps>, C<d_gethbyaddr>,
+C<d_gethbyname>, C<d_gethent>, C<d_gethname>, C<d_gethostprotos>,
+C<d_getlogin>, C<d_getmnt>, C<d_getmntent>, C<d_getnbyaddr>,
+C<d_getnbyname>, C<d_getnent>, C<d_getnetprotos>, C<d_getpbyname>,
+C<d_getpbynumber>, C<d_getpent>, C<d_getpgid>, C<d_getpgrp2>, C<d_getpgrp>,
+C<d_getppid>, C<d_getprior>, C<d_getprotoprotos>, C<d_getpwent>,
+C<d_getsbyname>, C<d_getsbyport>, C<d_getsent>, C<d_getservprotos>,
+C<d_getspent>, C<d_getspnam>, C<d_gettimeod>, C<d_gnulibc>, C<d_grpasswd>,
+C<d_hasmntopt>, C<d_htonl>, C<d_iconv>, C<d_index>, C<d_inetaton>,
+C<d_int64_t>, C<d_isascii>, C<d_killpg>, C<d_lchown>, C<d_ldbl_dig>,
+C<d_link>, C<d_locconv>, C<d_lockf>, C<d_longdbl>, C<d_longlong>,
+C<d_lseekproto>, C<d_lstat>, C<d_mblen>, C<d_mbstowcs>, C<d_mbtowc>,
+C<d_memchr>, C<d_memcmp>, C<d_memcpy>, C<d_memmove>, C<d_memset>,
+C<d_mkdir>, C<d_mkdtemp>, C<d_mkfifo>, C<d_mkstemp>, C<d_mkstemps>,
+C<d_mktime>, C<d_mmap>, C<d_mprotect>, C<d_msg>, C<d_msg_ctrunc>,
+C<d_msg_dontroute>, C<d_msg_oob>, C<d_msg_peek>, C<d_msg_proxy>,
+C<d_msgctl>, C<d_msgget>, C<d_msgrcv>, C<d_msgsnd>, C<d_msync>,
+C<d_munmap>, C<d_mymalloc>, C<d_nice>, C<d_nv_preserves_uv>, C<d_off64_t>,
 C<d_old_pthread_create_joinable>, C<d_oldpthreads>, C<d_oldsock>,
 C<d_open3>, C<d_pathconf>, C<d_pause>, C<d_phostname>, C<d_pipe>,
 C<d_poll>, C<d_portable>, C<d_PRId64>, C<d_PRIeldbl>, C<d_PRIEldbl>,
@@ -5484,14 +5563,14 @@ C<d_setprior>, C<d_setpwent>, C<d_setregid>, C<d_setresgid>,
 C<d_setresuid>, C<d_setreuid>, C<d_setrgid>, C<d_setruid>, C<d_setsent>,
 C<d_setsid>, C<d_setspent>, C<d_setvbuf>, C<d_sfio>, C<d_shm>, C<d_shmat>,
 C<d_shmatprototype>, C<d_shmctl>, C<d_shmdt>, C<d_shmget>, C<d_sigaction>,
-C<d_sigsetjmp>, C<d_socket>, C<d_sockpair>, C<d_sqrtl>, C<d_statblks>,
-C<d_statfs_f_flags>, C<d_statfs_s>, C<d_statvfs>, C<d_stdio_cnt_lval>,
-C<d_stdio_ptr_lval>, C<d_stdio_stream_array>, C<d_stdiobase>,
-C<d_stdstdio>, C<d_strchr>, C<d_strcoll>, C<d_strctcpy>, C<d_strerrm>,
-C<d_strerror>, C<d_strtod>, C<d_strtol>, C<d_strtold>, C<d_strtoll>,
-C<d_strtoul>, C<d_strtoull>, C<d_strtouq>, C<d_strxfrm>, C<d_suidsafe>,
-C<d_symlink>, C<d_syscall>, C<d_sysconf>, C<d_sysernlst>, C<d_syserrlst>,
-C<d_system>, C<d_tcgetpgrp>, C<d_tcsetpgrp>, C<d_telldir>,
+C<d_sigsetjmp>, C<d_socket>, C<d_socklen_t>, C<d_sockpair>, C<d_sqrtl>,
+C<d_statblks>, C<d_statfs_f_flags>, C<d_statfs_s>, C<d_statvfs>,
+C<d_stdio_cnt_lval>, C<d_stdio_ptr_lval>, C<d_stdio_stream_array>,
+C<d_stdiobase>, C<d_stdstdio>, C<d_strchr>, C<d_strcoll>, C<d_strctcpy>,
+C<d_strerrm>, C<d_strerror>, C<d_strtod>, C<d_strtol>, C<d_strtold>,
+C<d_strtoll>, C<d_strtoul>, C<d_strtoull>, C<d_strtouq>, C<d_strxfrm>,
+C<d_suidsafe>, C<d_symlink>, C<d_syscall>, C<d_sysconf>, C<d_sysernlst>,
+C<d_syserrlst>, C<d_system>, C<d_tcgetpgrp>, C<d_tcsetpgrp>, C<d_telldir>,
 C<d_telldirproto>, C<d_time>, C<d_times>, C<d_truncate>, C<d_tzname>,
 C<d_umask>, C<d_uname>, C<d_union_semun>, C<d_ustat>, C<d_vendorbin>,
 C<d_vendorlib>, C<d_vfork>, C<d_void_closedir>, C<d_voidsig>, C<d_voidtty>,
@@ -5524,16 +5603,17 @@ C<h_fcntl>, C<h_sysfile>, C<hint>, C<hostcat>, C<huge>
 C<i16size>, C<i16type>, C<i32size>, C<i32type>, C<i64size>, C<i64type>,
 C<i8size>, C<i8type>, C<i_arpainet>, C<i_bsdioctl>, C<i_db>, C<i_dbm>,
 C<i_dirent>, C<i_dld>, C<i_dlfcn>, C<i_fcntl>, C<i_float>, C<i_gdbm>,
-C<i_grp>, C<i_inttypes>, C<i_limits>, C<i_locale>, C<i_machcthr>,
-C<i_malloc>, C<i_math>, C<i_memory>, C<i_mntent>, C<i_ndbm>, C<i_netdb>,
-C<i_neterrno>, C<i_netinettcp>, C<i_niin>, C<i_poll>, C<i_pthread>,
-C<i_pwd>, C<i_rpcsvcdbm>, C<i_sfio>, C<i_sgtty>, C<i_shadow>, C<i_socks>,
-C<i_stdarg>, C<i_stddef>, C<i_stdlib>, C<i_string>, C<i_sysaccess>,
-C<i_sysdir>, C<i_sysfile>, C<i_sysfilio>, C<i_sysin>, C<i_sysioctl>,
-C<i_sysmount>, C<i_sysndir>, C<i_sysparam>, C<i_sysresrc>, C<i_syssecrt>,
-C<i_sysselct>, C<i_syssockio>, C<i_sysstat>, C<i_sysstatfs>,
-C<i_sysstatvfs>, C<i_systime>, C<i_systimek>, C<i_systimes>, C<i_systypes>,
-C<i_sysuio>, C<i_sysun>, C<i_sysvfs>, C<i_syswait>, C<i_termio>,
+C<i_grp>, C<i_iconv>, C<i_inttypes>, C<i_limits>, C<i_locale>,
+C<i_machcthr>, C<i_malloc>, C<i_math>, C<i_memory>, C<i_mntent>, C<i_ndbm>,
+C<i_netdb>, C<i_neterrno>, C<i_netinettcp>, C<i_niin>, C<i_poll>,
+C<i_pthread>, C<i_pwd>, C<i_rpcsvcdbm>, C<i_sfio>, C<i_sgtty>, C<i_shadow>,
+C<i_socks>, C<i_stdarg>, C<i_stddef>, C<i_stdlib>, C<i_string>,
+C<i_sysaccess>, C<i_sysdir>, C<i_sysfile>, C<i_sysfilio>, C<i_sysin>,
+C<i_sysioctl>, C<i_syslog>, C<i_sysmman>, C<i_sysmode>, C<i_sysmount>,
+C<i_sysndir>, C<i_sysparam>, C<i_sysresrc>, C<i_syssecrt>, C<i_sysselct>,
+C<i_syssockio>, C<i_sysstat>, C<i_sysstatfs>, C<i_sysstatvfs>,
+C<i_systime>, C<i_systimek>, C<i_systimes>, C<i_systypes>, C<i_sysuio>,
+C<i_sysun>, C<i_sysutsname>, C<i_sysvfs>, C<i_syswait>, C<i_termio>,
 C<i_termios>, C<i_time>, C<i_unistd>, C<i_ustat>, C<i_utime>, C<i_values>,
 C<i_varargs>, C<i_varhdr>, C<i_vfork>, C<ignore_versioned_solibs>,
 C<inc_version_list>, C<inc_version_list_init>, C<incpath>, C<inews>,
@@ -5550,10 +5630,11 @@ C<known_extensions>, C<ksh>
 =item l
 
 C<large>, C<ld>, C<lddlflags>, C<ldflags>, C<ldlibpthname>, C<less>,
-C<lib_ext>, C<libc>, C<libperl>, C<libpth>, C<libs>, C<libswanted>,
-C<line>, C<lint>, C<lkflags>, C<ln>, C<lns>, C<locincpth>, C<loclibpth>,
-C<longdblsize>, C<longlongsize>, C<longsize>, C<lp>, C<lpr>, C<ls>,
-C<lseeksize>, C<lseektype>
+C<lib_ext>, C<libc>, C<libperl>, C<libpth>, C<libs>, C<libsdirs>,
+C<libsfiles>, C<libsfound>, C<libspath>, C<libswanted>, C<line>, C<lint>,
+C<lkflags>, C<ln>, C<lns>, C<locincpth>, C<loclibpth>, C<longdblsize>,
+C<longlongsize>, C<longsize>, C<lp>, C<lpr>, C<ls>, C<lseeksize>,
+C<lseektype>
 
 =item m
 
@@ -5563,8 +5644,9 @@ C<man3direxp>, C<man3ext>
 
 =item M
 
-C<Mcc>, C<medium>, C<mips_type>, C<mkdir>, C<models>, C<modetype>, C<more>,
-C<multiarch>, C<mv>, C<myarchname>, C<mydomain>, C<myhostname>, C<myuname>
+C<Mcc>, C<medium>, C<mips_type>, C<mkdir>, C<mmaptype>, C<models>,
+C<modetype>, C<more>, C<multiarch>, C<mv>, C<myarchname>, C<mydomain>,
+C<myhostname>, C<myuname>
 
 =item n
 
@@ -5579,14 +5661,15 @@ C<orderlib>, C<osname>, C<osvers>
 
 =item p
 
-C<package>, C<pager>, C<passcat>, C<patchlevel>, C<path_sep>, C<perl>
+C<package>, C<pager>, C<passcat>, C<patchlevel>, C<path_sep>, C<perl5>,
+C<perl>
 
 =item P
 
 C<PERL_REVISION>, C<PERL_SUBVERSION>, C<PERL_VERSION>, C<perladmin>,
-C<perlpath>, C<pg>, C<phostname>, C<pidtype>, C<plibpth>, C<pmake>, C<pr>,
-C<prefix>, C<prefixexp>, C<privlib>, C<privlibexp>, C<prototype>,
-C<ptrsize>
+C<perlpath>, C<pg>, C<phostname>, C<pidtype>, C<plibpth>, C<pm_apiversion>,
+C<pmake>, C<pr>, C<prefix>, C<prefixexp>, C<privlib>, C<privlibexp>,
+C<prototype>, C<ptrsize>
 
 =item q
 
@@ -5594,8 +5677,8 @@ C<quadkind>, C<quadtype>
 
 =item r
 
-C<randbits>, C<randfunc>, C<randseedtype>, C<ranlib>, C<rd_nodata>, C<rm>,
-C<rmail>, C<runnm>
+C<randbits>, C<randfunc>, C<randseedtype>, C<ranlib>, C<rd_nodata>,
+C<revision>, C<rm>, C<rmail>, C<runnm>
 
 =item s
 
@@ -5605,8 +5688,8 @@ C<shmattype>, C<shortsize>, C<shrpenv>, C<shsharp>, C<sig_count>,
 C<sig_name>, C<sig_name_init>, C<sig_num>, C<sig_num_init>, C<signal_t>,
 C<sitearch>, C<sitearchexp>, C<sitebin>, C<sitebinexp>, C<sitelib>,
 C<sitelibexp>, C<siteprefix>, C<siteprefixexp>, C<sizetype>, C<sleep>,
-C<smail>, C<small>, C<so>, C<sockethdr>, C<socketlib>, C<sort>,
-C<spackage>, C<spitshell>, C<split>, C<sPRId64>, C<sPRIeldbl>,
+C<smail>, C<small>, C<so>, C<sockethdr>, C<socketlib>, C<socksizetype>,
+C<sort>, C<spackage>, C<spitshell>, C<split>, C<sPRId64>, C<sPRIeldbl>,
 C<sPRIEldbl>, C<sPRIfldbl>, C<sPRIFldbl>, C<sPRIgldbl>, C<sPRIGldbl>,
 C<sPRIi64>, C<sPRIo64>, C<sPRIu64>, C<sPRIx64>, C<sPRIX64>, C<src>,
 C<ssizetype>, C<startperl>, C<startsh>, C<static_ext>, C<stdchar>,
@@ -5623,12 +5706,13 @@ C<touch>, C<tr>, C<trnl>, C<troff>
 
 C<u16size>, C<u16type>, C<u32size>, C<u32type>, C<u64size>, C<u64type>,
 C<u8size>, C<u8type>, C<uidformat>, C<uidsign>, C<uidsize>, C<uidtype>,
-C<uname>, C<uniq>, C<uquadtype>, C<use5005threads>, C<use64bits>, C<usedl>,
-C<useithreads>, C<uselargefiles>, C<uselongdouble>, C<uselonglong>,
-C<usemorebits>, C<usemultiplicity>, C<usemymalloc>, C<usenm>, C<useopcode>,
-C<useperlio>, C<useposix>, C<usesfio>, C<useshrplib>, C<usesocks>,
-C<usethreads>, C<usevendorprefix>, C<usevfork>, C<usrinc>, C<uuname>,
-C<uvoformat>, C<uvsize>, C<uvtype>, C<uvuformat>, C<uvxformat>
+C<uname>, C<uniq>, C<uquadtype>, C<use5005threads>, C<use64bitall>,
+C<use64bitint>, C<usedl>, C<useithreads>, C<uselargefiles>,
+C<uselongdouble>, C<usemorebits>, C<usemultiplicity>, C<usemymalloc>,
+C<usenm>, C<useopcode>, C<useperlio>, C<useposix>, C<usesfio>,
+C<useshrplib>, C<usesocks>, C<usethreads>, C<usevendorprefix>, C<usevfork>,
+C<usrinc>, C<uuname>, C<uvoformat>, C<uvsize>, C<uvtype>, C<uvuformat>,
+C<uvxformat>
 
 =item v
 
@@ -5637,7 +5721,7 @@ C<vendorprefix>, C<vendorprefixexp>, C<version>, C<vi>, C<voidflags>
 
 =item x
 
-C<xlibpth>
+C<xlibpth>, C<xs_apiversion>
 
 =item z
 
@@ -6035,6 +6119,8 @@ variables
 
 =item DESCRIPTION
 
+=item BUGS
+
 =back
 
 =head2 Env - perl module that imports environment variables
@@ -6057,6 +6143,8 @@ variables
 
 =item DESCRIPTION
 
+=item CAVEATS
+
 =item AUTHOR
 
 =item COPYRIGHT
@@ -7013,6 +7101,16 @@ file_name_is_absolute
 
 path
 
+splitpath
+
+splitdir
+
+catpath
+
+abs2rel
+
+rel2abs
+
 =over
 
 =item SEE ALSO
@@ -7059,6 +7157,8 @@ updir
 
 no_upwards
 
+case_tolerant
+
 file_name_is_absolute
 
 path
@@ -7099,10 +7199,12 @@ fixpath
 
 =item Methods always loaded
 
-catdir
+canonpath (override)
 
 =back
 
+catdir
+
 catfile
 
 curdir (override)
@@ -7115,10 +7217,22 @@ tmpdir (override)
 
 updir (override)
 
+case_tolerant (override)
+
 path (override)
 
 file_name_is_absolute (override)
 
+splitpath (override)
+
+splitdir (override)
+
+catpath (override)
+
+splitpath
+
+splitdir
+
 =over
 
 =item SEE ALSO
@@ -8387,7 +8501,7 @@ Constants, Macros
 
 =over
 
-=item Options
+=item podchecker()
 
 B<-warnings> =E<gt> I<val>
 
@@ -8395,24 +8509,62 @@ B<-warnings> =E<gt> I<val>
 
 =item DESCRIPTION
 
+=item DIAGNOSTICS
+
 =over
 
+=item Errors
+
+empty =headn, =over on line I<N> without closing =back, =item without
+previous =over, =back without previous =over, No argument for =begin, =end
+without =begin, Nested =begin's, =for without formatter specification,
+unresolved internal link I<NAME>, Unknown command "I<CMD>", Unknown
+interior-sequence "I<SEQ>", nested commands
+I<CMD>E<lt>...I<CMD>E<lt>...E<gt>...E<gt>, garbled entity I<STRING>, Entity
+number out of range, malformed link LE<lt>E<gt>, nonempty ZE<lt>E<gt>,
+empty XE<lt>E<gt>, Spurious text after =pod / =cut, Spurious character(s)
+after =back
+
 =item Warnings
 
-=back
+multiple occurence of link target I<name>, line containing nothing but
+whitespace in paragraph, file does not start with =head, No numeric
+argument for =over, previous =item has no contents, preceding non-item
+paragraph(s), =item type mismatch (I<one> vs. I<two>), I<N> unescaped
+C<E<lt>E<gt>> in paragraph, Unknown entity, No items in =over, No argument
+for =item, empty section in previous paragraph, Verbatim paragraph in NAME
+section, Hyperlinks
 
-=item DIAGNOSTICS
+=back
 
 =item RETURN VALUE
 
 =item EXAMPLES
 
+=item INTERFACE
+
+=back
+
+C<$checker-E<gt>poderror( @args )>, C<$checker-E<gt>poderror( {%opts},
+@args )>
+
+C<$checker-E<gt>num_errors()>
+
+C<$checker-E<gt>name()>
+
+C<$checker-E<gt>node()>
+
+C<$checker-E<gt>idx()>
+
+C<$checker-E<gt>hyperlink()>
+
+=over
+
 =item AUTHOR
 
 =back
 
-=head2 Pod::Checker, Pod::Hyperlink - class for manipulation of POD
-hyperlinks
+=head2 Pod::Find - find POD documents in directory trees
 
 =over
 
@@ -8420,13 +8572,14 @@ hyperlinks
 
 =item DESCRIPTION
 
-=item METHODS
+=item OPTIONS
 
-new(), parse(), markup($on,$off,$pageon,$pageoff), text(), warning(),
-page(), node(), type(), alttext(), line(), file()
+B<-verbose>, B<-perl>, B<-script>, B<-inc>
 
 =item AUTHOR
 
+=item SEE ALSO
+
 =back
 
 =head2 Pod::Html - module to convert pod files to HTML
@@ -8711,6 +8864,110 @@ EE<lt>%sE<gt>, Unknown sequence %s, Unmatched =back
 
 =back
 
+=head2 Pod::ParseUtils - helpers for POD parsing and conversion
+
+=over
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=over
+
+=item Pod::List
+
+new()
+
+=back
+
+file()
+
+start()
+
+indent()
+
+type()
+
+rx()
+
+item()
+
+parent()
+
+tag()
+
+=over
+
+=item Pod::Hyperlink
+
+new()
+
+=back
+
+parse($string)
+
+markup($string)
+
+text()
+
+warning()
+
+line(), file()
+
+page()
+
+node()
+
+alttext()
+
+type()
+
+link()
+
+=over
+
+=item Pod::Cache
+
+new()
+
+=back
+
+item()
+
+find_page($name)
+
+=over
+
+=item Pod::Cache::Item
+
+new()
+
+=back
+
+page()
+
+description()
+
+path()
+
+file()
+
+nodes()
+
+find_node($name)
+
+idx()
+
+=over
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
 =head2 Pod::Parser - base class for creating POD filters and translators
 
 =over
@@ -9299,7 +9556,26 @@ closelog
 
 =item EXAMPLES
 
-=item DEPENDENCIES
+=item SEE ALSO
+
+=item AUTHOR
+
+=back
+
+=head2 Syslog::Syslog, Sys::Syslog, openlog, closelog, setlogmask, syslog -
+Perl interface to the UNIX syslog(3) calls
+
+=over
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+openlog $ident, $logopt, $facility, syslog $priority, $format, @args,
+setlogmask $mask_priority, setlogsock $sock_type (added in 5.004_02),
+closelog
+
+=item EXAMPLES
 
 =item SEE ALSO
 
@@ -9495,7 +9771,8 @@ unexpand(1)
 
 =back
 
-=head2 Thread - multithreading
+=head2 Thread - manipulate threads in Perl (EXPERIMENTAL, subject to
+change)
 
 =over