This is patch.2b1g to perl5.002beta1.

cd to your perl source directory, and type
	patch -p1 -N < patch.2b1g

This patch is just my packaging of Tom's documentation patches
he released as patch.2b1g.

Patch and enjoy,

    Andy Dougherty		doughera@lafcol.lafayette.edu
    Dept. of Physics
    Lafayette College, Easton PA 18042

1 files changed, 4 insertions, 351 deletions

diff --git a/pod/perlovl.pod b/pod/perlovl.pod
index cdb3ba66c5..1bad3221f3 100644
--- a/pod/perlovl.pod
+++ b/pod/perlovl.pod
@@ -1,355 +1,8 @@
-=head1 NAME 
+=head1 NAME
 
-perlovl - perl overloading semantics
+perlovl - overload perl mathematical functions [superseded]
 
-=head1 SYNOPSIS
+=head1
 
-    package SomeThing;
+This man page has been superseded by L<overload>.
 
-    %OVERLOAD = (
-	'+' => \&myadd,
-	'-' => \&mysub,
-	# etc
-    );
-    ...
-
-    package main;
-    $a = new SomeThing 57;
-    $b=5+$a;
-
-=head1 CAVEAT SCRIPTOR
-
-Overloading of operators is a subject not to be taken lightly.
-Neither its precise implementation, syntax, nor semantics are
-100% endorsed by Larry Wall.  So any of these may be changed 
-at some point in the future.
-
-=head1 DESCRIPTION
-
-=head2 Declaration of overloaded functions
-
-    package Number;
-    %OVERLOAD = ( 
-	"+" => \&add, 
-	"*=" => "muas"
-    );
-
-declares function Number::add() for addition, and method muas() in
-the "class" C<Number> (or one of its base classes)
-for the assignment form C<*=> of multiplication.  Legal values of this
-hash array are values legal inside C<&{ ... }> call, so the name of a
-subroutine, a reference to a subroutine, or an anonymous subroutine 
-will all work.
-
-The subroutine C<$OVERLOAD{"+"}> will be called to execute C<$a+$b> if $a
-is a reference to an object blessed into the package C<Number>, or $a is
-not an object from a package with defined mathemagic addition, but $b is a
-reference to a C<Number>.  It can be called also in other situations, like
-C<$a+=7>, or C<$a++>.  See L<MAGIC AUTOGENERATION>.  (Mathemagical
-methods refer to methods triggered by an overloaded mathematical
-operator.)
-
-=head2 Calling Conventions for Binary Operations
-
-The functions in C<values %OVERLOAD> are called with three (in one
-particular case with four, see L<Last Resort>) arguments.  If the
-corresponding operation is binary, then the first two arguments are the
-two arguments of the operation.  However, due to general object calling
-conventions, the first argument should be always an object in the package,
-so in the situation of C<7+$a>, the order of arguments is interchanged.
-Most probably it does not matter for implementation of the addition
-method, but whether the arguments are reversed is vital for the
-subtraction method.  The subroutine can query this information by
-examining the third argument, which can take three different values:
-
-=over 7
-
-=item FALSE
-
-the order of arguments is as in the current operation.
-
-=item TRUE
-
-the arguments are reversed.
-
-=item C<undef>
-
-the current operation is an assignment variant (as in
-C<$a+=7>), but the usual function is called instead.  This additional
-information can be used to generate some optimizations.
-
-=back
-
-=head2 Calling Conventions for Unary Operations
-
-Unary operation are considered binary operations with the second
-argument being C<undef>.  Thus C<$OVERLOAD{"++"}> is called with
-arguments C<($a,undef,'')> when $a++ is executed.
-
-=head2 Overloadable Operations
-
-The following keys of %OVERLOAD are recognized:
-
-=over 5
-
-=item * I<Arithmetic operations>
-
-    "+", "+=", "-", "-=", "*", "*=", "/", "/=", "%", "%=",
-    "**", "**=", "<<", "<<=", ">>", ">>=", "x", "x=", ".", ".=",
-
-For these operations a substituted non-assignment variant can be called if
-the assignment variant is not available.  Methods for operations "C<+>",
-"C<->", "C<+=>", and "C<-=>" can be called to automatically generate
-increment and decrement methods.  The operations "C<->" can be used to
-autogenerate missing methods for unary minus or C<abs>.
-
-=item * I<Comparison operations>
-
-    "<",  "<=", ">",  ">=", "==", "!=", "<=>",
-    "lt", "le", "gt", "ge", "eq", "ne", "cmp",
-
-If the corresponding "spaceship" variant is available, it can be
-used to substitute for the missing operation.  During C<sort>ing
-arrays, C<cmp> is used to compare values subject to %OVERLOAD.
-
-=item * I<Bit operations>
-
-    "&", "^", "|", "&=", "^=", "|=", "neg", "!", "~",
-
-"C<neg>" stands for unary minus.  If the method for C<neg> is not
-specified, it can be autogenerated using on the method for subtraction.
-
-=item * I<Increment and decrement>
-
-    "++", "--",
-
-If undefined, addition and subtraction methods can be
-used instead.  These operations are called both in prefix and
-postfix form.
-
-=item * I<Transcendental functions>
-
-    "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.
-
-=item * I<Boolean, string and numeric conversion>
-
-    "bool", "\"\"", "0+",
-
-If one or two of these operations are unavailable, the remaining ones can
-be used instead.  C<bool> is used in the flow control operators
-(like C<while>) and for the ternary "C<?:>" operation.  These functions can
-return any arbitrary Perl value.  If the corresponding operation for this value
-is overloaded too, that operation will be called again with this value.
-
-=item * I<Special>
-
-    "nomethod", "fallback", "=",
-
-see L<SPECIAL KEYS OF %OVERLOAD>.
-
-=back
-
-See L<"Fallback"> for an explanation of when a missing method can be autogenerated.
-
-=head1 SPECIAL KEYS OF %OVERLOAD
-
-Three keys are recognized by Perl that are not covered by the above
-description.
-
-=head2  Last Resort
-
-C<$OVERLOAD{"nomethod"}> is a reference to a function of four parameters.
-If defined, it is called when the overloading mechanism cannot find a
-method for some operation.  The first three arguments of this function
-coincide with arguments for the corresponding method if it were found, the
-fourth argument is the key of %OVERLOAD corresponding to the missing
-method.  If several methods are tried, the last one is used.  Say, C<1-$a>
-can be equivalent to
-
-	&{ $Pack::OVERLOAD{"nomethod"} }($a,1,1,"-").
-
-If some operation cannot be resolved, and there is no
-C<$OVERLOAD{"nomethod"}>, then an exception will be raised 
-via die() -- unless C<$OVERLOAD{"fallback"}> is true. 
-
-=head2 Fallback 
-
-C<$OVERLOAD{"fallback"}> governs what to do if a method for a particular
-operation is not found.  Three different cases are possible depending on
-value of C<$OVERLOAD{"fallback"}>:
-
-=over 16
-
-=item * C<undef>
-
-Perl tries to use a
-substituted method (see L<MAGIC AUTOGENERATION>).  If this fails, it
-then tries to calls C<$OVERLOAD{"nomethod"}>; if missing, an exception
-will be raised.
-
-=item * TRUE
-
-The same as for the C<undef> value, but no exception is raised.  Instead,
-it silently reverts to what it would have done were there no %OVERLOAD is
-present.
-
-=item * defined, but FALSE
-
-No autogeneration is tried.  Perl tries to call
-C<$OVERLOAD{"nomethod"}>, and if this is missing, raises an exception. 
-
-=back
-
-=head2 Copy Constructor
-
-C<$OVERLOAD{"="}> is a reference to a function with three arguments,
-i.e., it looks like a usual value of %OVERLOAD.  This operation
-is called in the situations when a mutator is applied to a reference
-that shares its object with some other reference, such as
-
-	$a=$b; 
-	$a++;
-
-To make this change to $a and not to change $b, a freshly made copy of
-C<$$a> is made, and $a is assigned a reference to this object.  This
-operation is executed during C<$a++>, (so before this C<$$a> coincides
-with C<$$b>), and only if C<++> is expressed via  C<$OPERATOR{'++'}> or
-C<$OPERATOR{'+='}>.  Note that if this operation is expressed via 'C<+>',
-i.e., as
-
-	$a=$b; 
-	$a=$a+1;
-
-then C<$$a> and C<$$b> do not appear as lvalues.
-
-If the copy constructor is required during execution of some mutator, but
-C<$OPERATOR{'='}> is missing, it can be autogenerated as a string
-copy if an object of
-the package is a plain scalar.
-
-=head1 MAGIC AUTOGENERATION
-
-If a method for an operation is not found, and C<$OVERLOAD{"fallback"}> is
-TRUE or undefined, Perl tries to to autogenerate a substitute method for
-the missing operation based on defined operations.  Autogenerated method
-substitutions are possible for the following operations:
-
-=over 16
-
-=item I<Assignment forms of arithmetic operations>
-
-C<$a=+$b> can use the C<$OVERLOAD{"+"}> method if C<$OVERLOAD{"+="}>
-is not defined.
-
-=item I<Conversion operations> 
-
-String, numeric, and boolean conversion are calculated in terms of one
-another if not all of them are defined.
-
-=item I<Increment and decrement>
-
-The C<++$a> operation can be expressed in terms of C<$a+=1> or C<$a+1>,
-and C<$a--> in terms of C<$a-=1> and C<$a-1>.
-
-=item C<abs($a)>
-
-can be expressed in terms of C<$aE<lt>0> and C<-$a> (or C<0-$a>).
-
-=item I<Unary minus>
-
-can be expressed in terms of subtraction.
-
-=item I<Concatenation>
-
-can be expressed in terms of string conversion.
-
-=item I<Comparison operations> 
-
-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
-
-=item I<Copy operator>
-
-can be expressed in terms of assignment to the dereferenced value, if this
-value is scalar but not a reference.
-
-=back
-
-=head1 WARNING
-
-The restriction for the comparison operation is that even if, for example,
-`C<cmp>' should return a reference to a blessed object, the
-autogenerated `C<lt>'
-function will produce only a standard logical value based on the
-numerical value of the result of `C<cmp>'.  In particular, a working
-numeric conversion is needed in this case (possibly expressed in terms of
-other conversions).
-
-Similarly, C<.=>  and C<x=> operators lose their mathemagical properties
-if the string conversion substitution is applied.
-
-When you chop() a mathemagical object, it becomes promoted to a string
-first, and its mathemagical qualities is lost.  The same can happen with other
-operations as well.
-
-=head1 IMPLEMENTATION
-
-The table of methods for all operations is cached as a magic for the
-symbol table hash of the package.  It is rechecked for changes of
-%OVERLOAD and @ISA only during C<bless>ing; so if it is changed
-dynamically, you'll need an additional fake C<bless>ing to update the
-table.
-
-(Every SVish thing has a magic queue, and a magic is an entry in that queue.
-This is how a single variable may participate in multiple forms of magic
-simultaneously.  For instance, environment variables regularly have two
-forms at once: their %ENV magic and their taint magic.)
-
-If an object belongs to a package with %OVERLOAD, it carries a special
-flag.  Thus the only speed penalty during arithmetic operations without
-overload is the check of this flag.
-
-In fact, if no %OVERLOAD is ever accessed, there is almost no overhead for
-overloadable operations, so most programs should not suffer measurable
-performance penalties.  Considerable effort was made minimize overhead
-when %OVERLOAD is accessed and the current operation is overloadable but
-the arguments in question do not belong to packages with %OVERLOAD.  When
-in doubt, test your speed with %OVERLOAD and without it.  So far there
-have been no reports of substantial speed degradation if Perl is compiled
-with optimization turned on.
-
-There is no size penalty for data if there is no %OVERLOAD. 
-
-The copying like C<$a=$b> is shallow; however, a one-level-deep
-copying is 
-carried out before any operation that can imply an assignment to the
-object $b (or $a) refers to, like C<$b++>.  You can override this
-behavior by defining your copy constructor (see L<"Copy Constructor">).
-
-It is expected that arguments to methods that are not explicitly supposed
-to be changed are constant (but this is not enforced).
-
-=head1 AUTHOR
-
-Ilya Zakharevich <F<ilya@math.mps.ohio-state.edu>>.
-
-=head1 DIAGNOSTICS
-
-When Perl is run with the B<-Do> switch or its equivalent, overloading
-induces diagnostic messages.
-
-=head1 BUGS
-
-Because it's used for overloading, the per-package associative array
-%OVERLOAD now has a special meaning in Perl.
-
-As shipped, %OVERLOAD is not inherited via the @ISA tree.  A patch for
-this is available from the author.
-
-This document is confusing.