This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Clean up POD for Math::BigInt and Math::BigFloat
authorTony Cook <tony@develop-help.com>
Fri, 23 Aug 2013 00:34:09 +0000 (10:34 +1000)
committerTony Cook <tony@develop-help.com>
Fri, 23 Aug 2013 00:34:40 +0000 (10:34 +1000)
Based on work done by Peter John Acklam, differences from his original
patch:

- links to items (which have been corrected by others) have been retained

- unnecessary conversion of < and > to E<lt> and E<gt> has been skipped.

- =over N has been converted to =over

- adjusted white-space in many places to avoid hitting column 80 in
  perldoc for verbatim text

dist/Math-BigInt/lib/Math/BigFloat.pm
dist/Math-BigInt/lib/Math/BigInt.pm

index 262e087..495bff1 100644 (file)
@@ -3808,6 +3808,7 @@ sub length
   }
 
 1;
+
 __END__
 
 =head1 NAME
@@ -3943,12 +3944,12 @@ declare your big floating point numbers as
 Operations with overloaded operators preserve the arguments, which is
 exactly what you expect.
 
-=head2 Canonical notation
+=head2 Input
 
 Input to these routines are either BigFloat objects, or strings of the
 following four forms:
 
-=over 2
+=over
 
 =item *
 
@@ -3996,16 +3997,16 @@ Some routines (C<is_odd()>, C<is_even()>, C<is_zero()>, C<is_one()>,
 C<is_nan()>) return true or false, while others (C<bcmp()>, C<bacmp()>)
 return either undef, <0, 0 or >0 and are suited for sort.
 
-Actual math is done by using the class defined with C<< with => Class; >> (which
-defaults to BigInts) to represent the mantissa and exponent.
+Actual math is done by using the class defined with C<< with => Class; >>
+(which defaults to BigInts) to represent the mantissa and exponent.
 
 The sign C</^[+-]$/> is stored separately. The string 'NaN' is used to 
 represent the result when input arguments are not numbers, as well as 
 the result of dividing by zero.
 
-=head2 C<mantissa()>, C<exponent()> and C<parts()>
+=head2 mantissa(), exponent() and parts()
 
-C<mantissa()> and C<exponent()> return the said parts of the BigFloat 
+mantissa() and exponent() return the said parts of the BigFloat
 as BigInts such that:
 
        $m = $x->mantissa();
@@ -4080,7 +4081,7 @@ functions like so:
 
 =head2 Rounding
 
-=over 2
+=over
 
 =item ffround ( +$scale )
 
@@ -4136,14 +4137,16 @@ calculates non-integer results when possible. Please see L<Math::BigInt>
 for a full description of each method. Below are just the most important
 differences:
 
-=head2 accuracy
+=over
+
+=item accuracy()
 
-        $x->accuracy(5);             # local for $x
-        CLASS->accuracy(5);          # global for all members of CLASS
-                                     # Note: This also applies to new()!
+      $x->accuracy(5);             # local for $x
+      CLASS->accuracy(5);          # global for all members of CLASS
+                                   # Note: This also applies to new()!
 
-        $A = $x->accuracy();         # read out accuracy that affects $x
-        $A = CLASS->accuracy();      # read out global accuracy
+      $A = $x->accuracy();         # read out accuracy that affects $x
+      $A = CLASS->accuracy();      # read out global accuracy
 
 Set or get the global or local accuracy, aka how many significant digits the
 results have. If you set a global accuracy, then this also applies to new()!
@@ -4161,25 +4164,25 @@ to the math operation as additional parameter:
         print scalar $x->copy()->bdiv($y, 2);           # print 4300
         print scalar $x->copy()->bdiv($y)->bround(2);   # print 4300
 
-=head2 precision()
+=item precision()
 
-        $x->precision(-2);      # local for $x, round at the second
-                                # digit right of the dot
-        $x->precision(2);       # ditto, round at the second digit left
-                                # of the dot
+      $x->precision(-2);      # local for $x, round at the second
+                              # digit right of the dot
+      $x->precision(2);       # ditto, round at the second digit left
+                              # of the dot
 
-        CLASS->precision(5);    # Global for all members of CLASS
-                                # This also applies to new()!
-        CLASS->precision(-5);   # ditto
+      CLASS->precision(5);    # Global for all members of CLASS
+                              # This also applies to new()!
+      CLASS->precision(-5);   # ditto
 
-        $P = CLASS->precision();    # read out global precision
-        $P = $x->precision();       # read out precision that affects $x
+      $P = CLASS->precision();    # read out global precision
+      $P = $x->precision();       # read out precision that affects $x
 
-Note: You probably want to use L</accuracy> instead. With L</accuracy> you
+Note: You probably want to use L</accuracy()> instead. With L</accuracy()> you
 set the number of digits each result should have, with L</precision()> you
 set the place where to round!
 
-=head2 bexp()
+=item bexp()
 
        $x->bexp($accuracy);            # calculate e ** X
 
@@ -4187,7 +4190,7 @@ Calculates the expression C<e ** $x> where C<e> is Euler's number.
 
 This method was added in v1.82 of Math::BigInt (April 2007).
 
-=head2 bnok()
+=item bnok()
 
        $x->bnok($y);   # x over y (binomial coefficient n over k)
 
@@ -4200,7 +4203,7 @@ function. The result is equivalent to:
 
 This method was added in v1.84 of Math::BigInt (April 2007).
 
-=head2 bpi()
+=item bpi()
 
        print Math::BigFloat->bpi(100), "\n";
 
@@ -4209,7 +4212,7 @@ rounded according to the current rounding mode, which defaults to "even".
 
 This method was added in v1.87 of Math::BigInt (June 2007).
 
-=head2 bcos()
+=item bcos()
 
        my $x = Math::BigFloat->new(1);
        print $x->bcos(100), "\n";
@@ -4218,7 +4221,7 @@ Calculate the cosinus of $x, modifying $x in place.
 
 This method was added in v1.87 of Math::BigInt (June 2007).
 
-=head2 bsin()
+=item bsin()
 
        my $x = Math::BigFloat->new(1);
        print $x->bsin(100), "\n";
@@ -4227,7 +4230,7 @@ Calculate the sinus of $x, modifying $x in place.
 
 This method was added in v1.87 of Math::BigInt (June 2007).
 
-=head2 batan2()
+=item batan2()
 
        my $y = Math::BigFloat->new(2);
        my $x = Math::BigFloat->new(3);
@@ -4238,7 +4241,7 @@ See also L</batan()>.
 
 This method was added in v1.87 of Math::BigInt (June 2007).
 
-=head2 batan()
+=item batan()
 
        my $x = Math::BigFloat->new(1);
        print $x->batan(100), "\n";
@@ -4247,7 +4250,7 @@ Calculate the arcus tanges of $x, modifying $x in place. See also L</batan2()>.
 
 This method was added in v1.87 of Math::BigInt (June 2007).
 
-=head2 bmuladd()
+=item bmuladd()
 
        $x->bmuladd($y,$z);
 
@@ -4255,6 +4258,8 @@ Multiply $x by $y, and then add $z to the result.
 
 This method was added in v1.87 of Math::BigInt (June 2007).
 
+=back
+
 =head1 Autocreating constants
 
 After C<use Math::BigFloat ':constant'> all the floating point constants
@@ -4363,7 +4368,7 @@ and B<VERY BAD THINGS> will happen when you use these together:
 
        my $flash_and_bang = $matter + $anti_matter;    # Don't do this!
 
-=over 1
+=over
 
 =item stringify, bstr()
 
@@ -4371,7 +4376,7 @@ Both stringify and bstr() now drop the leading '+'. The old code would return
 '+1.23', the new returns '1.23'. See the documentation in L<Math::BigInt> for
 reasoning and details.
 
-=item bdiv
+=item bdiv()
 
 The following will probably not print what you expect:
 
@@ -4385,7 +4390,7 @@ bdiv() will modify $c, so be careful. You probably want to use
 
 instead.
 
-=item brsft
+=item brsft()
 
 The following will probably not print what you expect:
 
@@ -4414,7 +4419,7 @@ a second reference to the B<same> object and stores it in $y. Thus anything
 that modifies $x will modify $y (except overloaded math operators), and vice
 versa. See L<Math::BigInt> for details and how to avoid that.
 
-=item bpow
+=item bpow()
 
 C<bpow()> now modifies the first argument, unlike the old code which left
 it alone and only returned the result. This is to be consistent with
@@ -4431,39 +4436,39 @@ a certain number of digits:
 
     use Math::BigFloat;
 
-    Math::BigFloat->precision(4);           # does not do what you
-                                            # think it does
-    my $x = Math::BigFloat->new(12345);             # rounds $x to "12000"!
-    print "$x\n";                           # print "12000"
-    my $y = Math::BigFloat->new(3);         # rounds $y to "0"!
-    print "$y\n";                           # print "0"
-    $z = $x / $y;                           # 12000 / 0 => NaN!
+    Math::BigFloat->precision(4);          # does not do what you
+                                           # think it does
+    my $x = Math::BigFloat->new(12345);            # rounds $x to "12000"!
+    print "$x\n";                          # print "12000"
+    my $y = Math::BigFloat->new(3);        # rounds $y to "0"!
+    print "$y\n";                          # print "0"
+    $z = $x / $y;                          # 12000 / 0 => NaN!
     print "$z\n";
-    print $z->precision(),"\n";                     # 4
+    print $z->precision(),"\n";                    # 4
 
-Replacing L</precision()> with L</accuracy> is probably not what you want, either:
+Replacing L</precision()> with L</accuracy()> is probably not what you want, either:
 
     use Math::BigFloat;
 
-    Math::BigFloat->accuracy(4);            # enables global rounding:
-    my $x = Math::BigFloat->new(123456);     # rounded immediately
-                                             #   to "12350"
-    print "$x\n";                           # print "123500"
-    my $y = Math::BigFloat->new(3);         # rounded to "3
-    print "$y\n";                           # print "3"
-    print $z = $x->copy()->bdiv($y),"\n";    # 41170
-    print $z->accuracy(),"\n";              # 4
+    Math::BigFloat->accuracy(4);           # enables global rounding:
+    my $x = Math::BigFloat->new(123456);    # rounded immediately
+                                            #   to "12350"
+    print "$x\n";                          # print "123500"
+    my $y = Math::BigFloat->new(3);        # rounded to "3
+    print "$y\n";                          # print "3"
+    print $z = $x->copy()->bdiv($y),"\n";   # 41170
+    print $z->accuracy(),"\n";             # 4
 
 What you want to use instead is:
 
     use Math::BigFloat;
 
-    my $x = Math::BigFloat->new(123456);     # no rounding
-    print "$x\n";                           # print "123456"
-    my $y = Math::BigFloat->new(3);         # no rounding
-    print "$y\n";                           # print "3"
-    print $z = $x->copy()->bdiv($y,4),"\n";  # 41150
-    print $z->accuracy(),"\n";              # undef
+    my $x = Math::BigFloat->new(123456);    # no rounding
+    print "$x\n";                          # print "123456"
+    my $y = Math::BigFloat->new(3);        # no rounding
+    print "$y\n";                          # print "3"
+    print $z = $x->copy()->bdiv($y,4),"\n"; # 41150
+    print $z->accuracy(),"\n";             # undef
 
 In addition to computing what you expected, the last example also does B<not>
 "taint" the result with an accuracy or precision setting, which would
index ff11687..491b815 100644 (file)
@@ -3467,9 +3467,7 @@ declare your big integers as
 Operations with overloaded operators preserve the arguments which is
 exactly what you expect.
 
-=over 2
-
-=item Input
+=head2 Input
 
 Input values to these routines may be any string, that looks like a number
 and results in an integer, including hexadecimal and binary numbers.
@@ -3507,7 +3505,7 @@ C<bnorm()> on a BigInt object is now effectively a no-op, since the numbers
 are always stored in normalized form. If passed a string, creates a BigInt 
 object from the input.
 
-=item Output
+=head2 Output
 
 Output values are BigInt objects (normalized), except for the methods which
 return a string (see L</SYNOPSIS>).
@@ -3516,8 +3514,6 @@ Some routines (C<is_odd()>, C<is_even()>, C<is_zero()>, C<is_one()>,
 C<is_nan()>, etc.) return true or false, while others (C<bcmp()>, C<bacmp()>)
 return either undef (if NaN is involved), <0, 0 or >0 and are suited for sort.
 
-=back
-
 =head1 METHODS
 
 Each of the methods below (except config(), accuracy() and precision())
@@ -3525,7 +3521,9 @@ accepts three additional parameters. These arguments C<$A>, C<$P> and C<$R>
 are C<accuracy>, C<precision> and C<round_mode>. Please see the section about
 L</ACCURACY and PRECISION> for more information.
 
-=head2 config()
+=over
+
+=item config()
 
        use Data::Dumper;
 
@@ -3547,8 +3545,8 @@ appropriate information.
                      Math::BigInt
        upgrade       To which class math operations might be upgraded
                      Math::BigFloat
-       downgrade     To which class math operations might be downgraded
-                     undef
+       downgrade     To which class math operations might be
+                     downgraded undef
        precision     Global precision
                      undef
        accuracy      Global accuracy
@@ -3575,7 +3573,7 @@ Example:
            { trap_inf => 1, precision => 5 }
        );
 
-=head2 accuracy()
+=item accuracy()
 
     $x->accuracy(5);        # local for $x
     CLASS->accuracy(5);             # global for all members of CLASS
@@ -3627,19 +3625,19 @@ globals separated from Math::BigInt, but it is possible to subclass
 Math::BigInt and make the globals of the subclass aliases to the ones from
 Math::BigInt.
 
-=head2 precision()
+=item precision()
 
-    $x->precision(-2);         # local for $x, round at the second
-                               # digit right of the dot
-    $x->precision(2);          # ditto, round at the second digit left
-                               # of the dot
+    $x->precision(-2);          # local for $x, round at the second
+                                # digit right of the dot
+    $x->precision(2);           # ditto, round at the second digit
+                                # left of the dot
 
-    CLASS->precision(5);       # Global for all members of CLASS
-                               # This also applies to new()!
-    CLASS->precision(-5);      # ditto
+    CLASS->precision(5);        # Global for all members of CLASS
+                                # This also applies to new()!
+    CLASS->precision(-5);       # ditto
 
-    $P = CLASS->precision();   # read out global precision
-    $P = $x->precision();      # read out precision that affects $x
+    $P = CLASS->precision();    # read out global precision
+    $P = $x->precision();       # read out precision that affects $x
 
 Note: You probably want to use L</accuracy()> instead. With L</accuracy()> you
 set the number of digits each result should have, with L</precision()> you
@@ -3666,7 +3664,7 @@ value represents the prevision that will be in effect for $x:
 
     $y = Math::BigInt->new(1234567);       # unrounded
     print Math::BigInt->precision(4),"\n";  # set 4, print 4
-    $x = Math::BigInt->new(123456);     # will be automatically rounded
+    $x = Math::BigInt->new(123456);    # will be automatically rounded
     print $x;                              # print "120000"!
 
 Note: Works also for subclasses like L<Math::BigFloat>. Each class has its
@@ -3674,7 +3672,7 @@ own globals separated from Math::BigInt, but it is possible to subclass
 Math::BigInt and make the globals of the subclass aliases to the ones from
 Math::BigInt.
 
-=head2 brsft()
+=item brsft()
 
        $x->brsft($y,$n);
 
@@ -3699,7 +3697,7 @@ There is one exception, and that is base 2 with negative $x:
 This will print -3, not -2 (as it would if you divide -5 by 2 and truncate the
 result).
 
-=head2 new()
+=item new()
 
        $x = Math::BigInt->new($str,$A,$P,$R);
 
@@ -3709,7 +3707,7 @@ input is accepted as decimal, hex (with leading '0x') or binary (with leading
 
 See L</Input> for more info on accepted input formats.
 
-=head2 from_oct()
+=item from_oct()
 
        $x = Math::BigInt->from_oct("0775");    # input is octal
 
@@ -3718,7 +3716,7 @@ Interpret the input as an octal string and return the corresponding value. A
 right after the prefix, if present, or between any two digits. If the input is
 invalid, a NaN is returned.
 
-=head2 from_hex()
+=item from_hex()
 
        $x = Math::BigInt->from_hex("0xcafe");  # input is hexadecimal
 
@@ -3726,7 +3724,7 @@ Interpret input as a hexadecimal string. A "0x" or "x" prefix is optional. A
 single underscore character may be placed right after the prefix, if present,
 or between any two digits. If the input is invalid, a NaN is returned.
 
-=head2 from_bin()
+=item from_bin()
 
        $x = Math::BigInt->from_bin("0b10011"); # input is binary
 
@@ -3734,7 +3732,7 @@ Interpret the input as a binary string. A "0b" or "b" prefix is optional. A
 single underscore character may be placed right after the prefix, if present,
 or between any two digits. If the input is invalid, a NaN is returned.
 
-=head2 bnan()
+=item bnan()
 
        $x = Math::BigInt->bnan();
 
@@ -3743,7 +3741,7 @@ If used on an object, it will set it to NaN:
 
        $x->bnan();
 
-=head2 bzero()
+=item bzero()
 
        $x = Math::BigInt->bzero();
 
@@ -3752,7 +3750,7 @@ If used on an object, it will set it to zero:
 
        $x->bzero();
 
-=head2 binf()
+=item binf()
 
        $x = Math::BigInt->binf($sign);
 
@@ -3763,7 +3761,7 @@ If used on an object, it will set it to infinity:
        $x->binf();
        $x->binf('-');
 
-=head2 bone()
+=item bone()
 
        $x = Math::BigInt->binf($sign);
 
@@ -3774,7 +3772,7 @@ If used on an object, it will set it to one:
        $x->bone();             # +1
        $x->bone('-');          # -1
 
-=head2 is_one()/is_zero()/is_nan()/is_inf()
+=item is_one()/is_zero()/is_nan()/is_inf()
 
        $x->is_zero();          # true if arg is +0
        $x->is_nan();           # true if arg is NaN
@@ -3789,7 +3787,7 @@ like:
 
        if ($x == 0)
 
-=head2 is_pos()/is_neg()/is_positive()/is_negative()
+=item is_pos()/is_neg()/is_positive()/is_negative()
 
        $x->is_pos();                   # true if > 0
        $x->is_neg();                   # true if < 0
@@ -3805,7 +3803,7 @@ C<is_neg()>, respectively. C<is_positive()> and C<is_negative()> were
 introduced in v1.36, while C<is_pos()> and C<is_neg()> were only introduced
 in v1.68.
 
-=head2 is_odd()/is_even()/is_int()
+=item is_odd()/is_even()/is_int()
 
        $x->is_odd();                   # true if odd, false for even
        $x->is_even();                  # true if even, false for odd
@@ -3816,20 +3814,20 @@ C<-inf> are not integers and are neither odd nor even.
 
 In BigInt, all numbers except C<NaN>, C<+inf> and C<-inf> are integers.
 
-=head2 bcmp()
+=item bcmp()
 
        $x->bcmp($y);
 
 Compares $x with $y and takes the sign into account.
 Returns -1, 0, 1 or undef.
 
-=head2 bacmp()
+=item bacmp()
 
        $x->bacmp($y);
 
 Compares $x with $y while ignoring their sign. Returns -1, 0, 1 or undef.
 
-=head2 sign()
+=item sign()
 
        $x->sign();
 
@@ -3843,20 +3841,20 @@ If you want $x to have a certain sign, use one of the following methods:
        $x->binf();             # '+inf'
        $x->binf('-');          # '-inf'
 
-=head2 digit()
+=item digit()
 
-       $x->digit($n);       # return the nth digit, counting from right
+       $x->digit($n);     # return the nth digit, counting from right
 
 If C<$n> is negative, returns the digit counting from left.
 
-=head2 bneg()
+=item bneg()
 
        $x->bneg();
 
 Negate the number, e.g. change the sign between '+' and '-', or between '+inf'
 and '-inf', respectively. Does nothing for NaN or zero.
 
-=head2 babs()
+=item babs()
 
        $x->babs();
 
@@ -3864,18 +3862,18 @@ Set the number to its absolute value, e.g. change the sign from '-' to '+'
 and from '-inf' to '+inf', respectively. Does nothing for NaN or positive
 numbers.
 
-=head2 bsgn()
+=item bsgn()
 
        $x->bsgn();
 
 Signum function. Set the number to -1, 0, or 1, depending on whether the
 number is negative, zero, or positive, respectively. Does not modify NaNs.
 
-=head2 bnorm()
+=item bnorm()
 
        $x->bnorm();                    # normalize (no-op)
 
-=head2 bnot()
+=item bnot()
 
        $x->bnot();
 
@@ -3885,27 +3883,27 @@ Two's complement (bitwise not). This is equivalent to
 
 but faster.
 
-=head2 binc()
+=item binc()
 
        $x->binc();             # increment x by 1
 
-=head2 bdec()
+=item bdec()
 
        $x->bdec();             # decrement x by 1
 
-=head2 badd()
+=item badd()
 
        $x->badd($y);           # addition (add $y to $x)
 
-=head2 bsub()
+=item bsub()
 
        $x->bsub($y);           # subtraction (subtract $y from $x)
 
-=head2 bmul()
+=item bmul()
 
        $x->bmul($y);           # multiplication (multiply $x by $y)
 
-=head2 bmuladd()
+=item bmuladd()
 
        $x->bmuladd($y,$z);
 
@@ -3913,16 +3911,16 @@ Multiply $x by $y, and then add $z to the result,
 
 This method was added in v1.87 of Math::BigInt (June 2007).
 
-=head2 bdiv()
+=item bdiv()
 
        $x->bdiv($y);           # divide, set $x to quotient
                                # return (quo,rem) or quo if scalar
 
-=head2 bmod()
+=item bmod()
 
        $x->bmod($y);           # modulus (x % y)
 
-=head2 bmodinv()
+=item bmodinv()
 
        $x->bmodinv($mod);      # modular multiplicative inverse
 
@@ -3939,7 +3937,7 @@ If C<$x> and C<$y> are non-zero, they must be relative primes, i.e.,
 C<bgcd($y, $mod)==1>. 'C<NaN>' is returned when no modular multiplicative
 inverse exists.
 
-=head2 bmodpow()
+=item bmodpow()
 
        $num->bmodpow($exp,$mod);       # modular exponentiation
                                        # ($num**$exp % $mod)
@@ -3961,11 +3959,11 @@ is exactly equivalent to
 
        bmodinv($num, $mod)
 
-=head2 bpow()
+=item bpow()
 
        $x->bpow($y);                 # power of arguments (x ** y)
 
-=head2 blog()
+=item blog()
 
        $x->blog($base, $accuracy);   # logarithm of x to the base $base
 
@@ -3973,7 +3971,7 @@ If C<$base> is not defined, Euler's number (e) is used:
 
        print $x->blog(undef, 100);   # log(x) to 100 digits
 
-=head2 bexp()
+=item bexp()
 
        $x->bexp($accuracy);          # calculate e ** X
 
@@ -3983,7 +3981,7 @@ This method was added in v1.82 of Math::BigInt (April 2007).
 
 See also L</blog()>.
 
-=head2 bnok()
+=item bnok()
 
        $x->bnok($y);        # x over y (binomial coefficient n over k)
 
@@ -3996,7 +3994,7 @@ function. The result is equivalent to:
 
 This method was added in v1.84 of Math::BigInt (April 2007).
 
-=head2 bpi()
+=item bpi()
 
        print Math::BigInt->bpi(100), "\n";             # 3
 
@@ -4013,7 +4011,7 @@ current rounding mode:
 
 This method was added in v1.87 of Math::BigInt (June 2007).
 
-=head2 bcos()
+=item bcos()
 
        my $x = Math::BigInt->new(1);
        print $x->bcos(100), "\n";
@@ -4025,7 +4023,7 @@ integer.
 
 This method was added in v1.87 of Math::BigInt (June 2007).
 
-=head2 bsin()
+=item bsin()
 
        my $x = Math::BigInt->new(1);
        print $x->bsin(100), "\n";
@@ -4037,7 +4035,7 @@ integer.
 
 This method was added in v1.87 of Math::BigInt (June 2007).
 
-=head2 batan2()
+=item batan2()
 
        my $x = Math::BigInt->new(1);
        my $y = Math::BigInt->new(1);
@@ -4050,7 +4048,7 @@ integer.
 
 This method was added in v1.87 of Math::BigInt (June 2007).
 
-=head2 batan()
+=item batan()
 
        my $x = Math::BigFloat->new(0.5);
        print $x->batan(100), "\n";
@@ -4062,58 +4060,58 @@ integer.
 
 This method was added in v1.87 of Math::BigInt (June 2007).
 
-=head2 blsft()
+=item blsft()
 
        $x->blsft($y);          # left shift in base 2
        $x->blsft($y,$n);       # left shift, in base $n (like 10)
 
-=head2 brsft()
+=item brsft()
 
        $x->brsft($y);          # right shift in base 2
        $x->brsft($y,$n);       # right shift, in base $n (like 10)
 
-=head2 band()
+=item band()
 
        $x->band($y);                   # bitwise and
 
-=head2 bior()
+=item bior()
 
        $x->bior($y);                   # bitwise inclusive or
 
-=head2 bxor()
+=item bxor()
 
        $x->bxor($y);                   # bitwise exclusive or
 
-=head2 bnot()
+=item bnot()
 
        $x->bnot();                     # bitwise not (two's complement)
 
-=head2 bsqrt()
+=item bsqrt()
 
        $x->bsqrt();                    # calculate square-root
 
-=head2 broot()
+=item broot()
 
        $x->broot($N);
 
 Calculates the N'th root of C<$x>.
 
-=head2 bfac()
+=item bfac()
 
-       $x->bfac();                     # factorial of $x (1*2*3*4*..$x)
+       $x->bfac();                   # factorial of $x (1*2*3*4*..$x)
 
-=head2 round()
+=item round()
 
        $x->round($A,$P,$round_mode);
 
 Round $x to accuracy C<$A> or precision C<$P> using the round mode
 C<$round_mode>.
 
-=head2 bround()
+=item bround()
 
        $x->bround($N);               # accuracy: preserve $N digits
 
-=head2 bfround()
+=item bfround()
 
        $x->bfround($N);
 
@@ -4130,29 +4128,29 @@ Examples:
        123456.123456   -2              123456.12
        123456.123456   -3              123456.123
 
-=head2 bfloor()
+=item bfloor()
 
        $x->bfloor();
 
 Set $x to the integer less or equal than $x. This is a no-op in BigInt, but
 does change $x in BigFloat.
 
-=head2 bceil()
+=item bceil()
 
        $x->bceil();
 
 Set $x to the integer greater or equal than $x. This is a no-op in BigInt, but
 does change $x in BigFloat.
 
-=head2 bgcd()
+=item bgcd()
 
-       bgcd(@values);          # greatest common divisor (no OO style)
+       bgcd(@values);        # greatest common divisor (no OO style)
 
-=head2 blcm()
+=item blcm()
 
-       blcm(@values);          # lowest common multiple (no OO style)
+       blcm(@values);        # lowest common multiple (no OO style)
 
-head2 length()
+=item length()
 
        $x->length();
         ($xl,$fl) = $x->length();
@@ -4161,27 +4159,27 @@ Returns the number of digits in the decimal representation of the number.
 In list context, returns the length of the integer and fraction part. For
 BigInt's, the length of the fraction part will always be 0.
 
-=head2 exponent()
+=item exponent()
 
        $x->exponent();
 
 Return the exponent of $x as BigInt.
 
-=head2 mantissa()
+=item mantissa()
 
        $x->mantissa();
 
 Return the signed mantissa of $x as BigInt.
 
-=head2 parts()
+=item parts()
 
        $x->parts();    # return (mantissa,exponent) as BigInt
 
-=head2 copy()
+=item copy()
 
        $x->copy();     # make a true copy of $x (unlike $y = $x;)
 
-=head2 as_int()/as_number()
+=item as_int()/as_number()
 
        $x->as_int();
 
@@ -4191,29 +4189,29 @@ C<copy()>.
 C<as_number()> is an alias to this method. C<as_number> was introduced in
 v1.22, while C<as_int()> was only introduced in v1.68.
 
-=head2 bstr()
+=item bstr()
 
        $x->bstr();
 
 Returns a normalized string representation of C<$x>.
 
-=head2 bsstr()
+=item bsstr()
 
        $x->bsstr();    # normalized string in scientific notation
 
-=head2 as_hex()
+=item as_hex()
 
        $x->as_hex();   # as signed hexadecimal string with prefixed 0x
 
-=head2 as_bin()
+=item as_bin()
 
        $x->as_bin();   # as signed binary string with prefixed 0b
 
-=head2 as_oct()
+=item as_oct()
 
        $x->as_oct();   # as signed octal string with prefixed 0
 
-=head2 numify()
+=item numify()
 
        print $x->numify();
 
@@ -4222,7 +4220,7 @@ whenever a scalar is needed, for instance in array index operations.
 
 This loses precision, to avoid this use L<as_int()|/"as_int()/as_number()"> instead.
 
-=head2 modify()
+=item modify()
 
        $x->modify('bpowd');
 
@@ -4231,7 +4229,7 @@ operation, or 1 if not.
 
 This is used for instance by L<Math::BigInt::Constant>.
 
-=head2 upgrade()/downgrade()
+=item upgrade()/downgrade()
 
 Set/get the class for downgrade/upgrade operations. Thuis is used
 for instance by L<bignum>. The defaults are '', thus the following
@@ -4242,15 +4240,17 @@ operation will create a BigInt, not a BigFloat:
 
        print $i + $f,"\n";                     # print 246
 
-=head2 div_scale()
+=item div_scale()
 
 Set/get the number of digits for the default precision in divide
 operations.
 
-=head2 round_mode()
+=item round_mode()
 
 Set/get the current round mode.
 
+=back
+
 =head1 ACCURACY and PRECISION
 
 Since version v1.33, Math::BigInt and Math::BigFloat have full support for
@@ -4323,7 +4323,7 @@ When rounding a number, different 'styles' or 'kinds'
 of rounding are possible. (Note that random rounding, as in
 Math::Round, is not implemented.)
 
-=over 2
+=over
 
 =item 'trunc'
 
@@ -4388,7 +4388,7 @@ is 5 or greater, otherwise round down. E.g., 0.15 becomes 0.2 and
 The handling of A & P in MBI/MBF (the old core code shipped with Perl
 versions <= 5.7.2) is like this:
 
-=over 2
+=over
 
 =item Precision
 
@@ -4432,7 +4432,7 @@ versions <= 5.7.2) is like this:
 
 This is how it works now:
 
-=over 2
+=over
 
 =item Setting/Accessing
 
@@ -4614,7 +4614,7 @@ This is how it works now:
 
 While BigInt has extensive handling of inf and NaN, certain quirks remain.
 
-=over 2
+=over
 
 =item oct()/hex()
 
@@ -4881,7 +4881,7 @@ For more benchmark results see L<http://bloodgate.com/perl/benchmarks.html>.
 The basic design of Math::BigInt allows simple subclasses with very little
 work, as long as a few simple rules are followed:
 
-=over 2
+=over
 
 =item *
 
@@ -4950,7 +4950,7 @@ the class Foo::Bar. Usually this is used in conjunction with Math::BigFloat:
 
        use Math::BigInt upgrade => 'Math::BigFloat';
 
-As a shortcut, you can use the module C<bignum>:
+As a shortcut, you can use the module L<bignum>:
 
        use bignum;
 
@@ -4968,7 +4968,7 @@ Beware: This feature is not fully implemented yet.
 The following methods upgrade themselves unconditionally; that is if upgrade
 is in effect, they will always hand up their work:
 
-=over 2
+=over
 
 =item bsqrt()
 
@@ -4998,7 +4998,7 @@ C<Math::BigInt> exports nothing by default, but can export the following methods
 Some things might not work as you expect them. Below is documented what is
 known to be troublesome:
 
-=over 1
+=over
 
 =item bstr(), bsstr() and 'cmp'
 
@@ -5052,7 +5052,7 @@ comparing them as strings:
        $y = Math::BigInt->new($y);
        ok ($x,$y);                     # okay
 
-Alternatively, simple use C<< <=> >> for comparisons, this will get it
+Alternatively, simply use C<< <=> >> for comparisons, this will get it
 always right. There is not yet a way to get a number automatically represented
 as a string that matches exactly the way Perl represents it.
 
@@ -5087,7 +5087,7 @@ when you access an array:
 
        $z = $array[$x];                        # does work automatically
 
-=item length
+=item length()
 
 The following will probably not do what you expect:
 
@@ -5099,7 +5099,7 @@ since print calls C<length()> in list context. Use something like:
 
        print scalar $c->length(),"\n";         # prints 3
 
-=item bdiv
+=item bdiv()
 
 The following will probably not do what you expect:
 
@@ -5110,9 +5110,10 @@ context. Also, C<bdiv()> will modify $c, so be careful. You probably want
 to use
 
        print $c / 10000,"\n";
-       print scalar $c->bdiv(10000),"\n";  # or if you want to modify $c
 
-instead.
+or, if you want to  modify $c instead,
+
+       print scalar $c->bdiv(10000),"\n";
 
 The quotient is always the greatest integer less than or equal to the
 real-valued quotient of the two operands, and the remainder (when it is