Rewrap some verbatim pod in Math::BigInt

I started to make Math::BigInt’s pod fit within 79 columns, but
soon petered out.  At least this is better than nothing.

1 files changed, 127 insertions, 116 deletions

diff --git a/dist/Math-BigInt/lib/Math/BigInt.pm b/dist/Math-BigInt/lib/Math/BigInt.pm
index 36b10490f4..3da16ded7e 100644
--- a/dist/Math-BigInt/lib/Math/BigInt.pm
+++ b/dist/Math-BigInt/lib/Math/BigInt.pm
@@ -18,7 +18,7 @@ package Math::BigInt;
 my $class = "Math::BigInt";
 use 5.006002;
 
-$VERSION = '1.995';
+$VERSION = '1.996';
 
 @ISA = qw(Exporter);
 @EXPORT_OK = qw(objectify bgcd blcm); 
@@ -3344,9 +3344,10 @@ Math::BigInt - Arbitrary size integer/float math package
   $x->digit($n);	# return the nth digit, counting from right
   $x->digit(-$n);	# return the nth digit, counting from left
 
-  # The following all modify their first argument. If you want to preserve
-  # $x, use $z = $x->copy()->bXXX($y); See under L<CAVEATS> for why this is
-  # necessary when mixing $a = $b assignments with non-overloaded math.
+  # The following all modify their first argument. If you want to pre-
+  # serve $x, use $z = $x->copy()->bXXX($y); See under L<CAVEATS> for
+  # why this is necessary when mixing $a = $b assignments with non-over-
+  # loaded math.
 
   $x->bzero();		# set $x to 0
   $x->bnan();		# set $x to NaN
@@ -3377,10 +3378,12 @@ Math::BigInt - Arbitrary size integer/float math package
   $x->bpow($y);		   # power of arguments (x ** y)
   $x->blsft($y);	   # left shift in base 2
   $x->brsft($y);	   # right shift in base 2
-			   # returns (quo,rem) or quo if in scalar context
+			   # returns (quo,rem) or quo if in sca-
+			   # lar context
   $x->blsft($y,$n);	   # left shift by $y places in base $n
   $x->brsft($y,$n);	   # right shift by $y places in base $n
-			   # returns (quo,rem) or quo if in scalar context
+			   # returns (quo,rem) or quo if in sca-
+			   # lar context
 
   $x->band($y);		   # bitwise and
   $x->bior($y);		   # bitwise inclusive or
@@ -3397,7 +3400,8 @@ Math::BigInt - Arbitrary size integer/float math package
   $x->blog($base);	   # logarithm of $x to base $base (f.i. 2)
   $x->bexp();		   # calculate e ** $x where e is Euler's number
 
-  $x->round($A,$P,$mode);  # round to accuracy or precision using mode $mode
+  $x->round($A,$P,$mode);  # round to accuracy or precision using
+			   # mode $mode
   $x->bround($n);	   # accuracy: preserve $n digits
   $x->bfround($n);	   # $n > 0: round $nth digits,
 			   # $n < 0: round to the $nth digit after the
@@ -3417,36 +3421,38 @@ Math::BigInt - Arbitrary size integer/float math package
   my $lcm = Math::BigInt::blcm(@values);
 
   $x->length();		   # return number of digits in number
-  ($xl,$f) = $x->length(); # length of number and length of fraction part,
-			   # latter is always 0 digits long for BigInts
+  ($xl,$f) = $x->length(); # length of number and length of fraction
+			   # part, latter is always 0 digits long
+			   # for BigInts
 
-  $x->exponent();	   # return exponent as BigInt
-  $x->mantissa();	   # return (signed) mantissa as BigInt
-  $x->parts();		   # return (mantissa,exponent) as BigInt
-  $x->copy();		   # make a true copy of $x (unlike $y = $x;)
-  $x->as_int();		   # return as BigInt (in BigInt: same as copy())
-  $x->numify();		   # return as scalar (might overflow!)
+  $x->exponent();	  # return exponent as BigInt
+  $x->mantissa();	  # return (signed) mantissa as BigInt
+  $x->parts();		  # return (mantissa,exponent) as BigInt
+  $x->copy();		  # make a true copy of $x (unlike $y = $x;)
+  $x->as_int();		  # return as BigInt (in BigInt: same as copy())
+  $x->numify();		  # return as scalar (might overflow!)
 
   # conversion to string (do not modify their argument)
-  $x->bstr();		   # normalized string (e.g. '3')
-  $x->bsstr();		   # norm. string in scientific notation (e.g. '3E0')
-  $x->as_hex();		   # as signed hexadecimal string with prefixed 0x
-  $x->as_bin();		   # as signed binary string with prefixed 0b
-  $x->as_oct();		   # as signed octal string with prefixed 0
+  $x->bstr();	      # normalized string (e.g. '3')
+  $x->bsstr();	      # norm. string in scientific notation (e.g. '3E0')
+  $x->as_hex();	      # as signed hexadecimal string with prefixed 0x
+  $x->as_bin();	      # as signed binary string with prefixed 0b
+  $x->as_oct();	      # as signed octal string with prefixed 0
 
 
   # precision and accuracy (see section about rounding for more)
-  $x->precision();	   # return P of $x (or global, if P of $x undef)
-  $x->precision($n);	   # set P of $x to $n
-  $x->accuracy();	   # return A of $x (or global, if A of $x undef)
-  $x->accuracy($n);	   # set A $x to $n
+  $x->precision();	 # return P of $x (or global, if P of $x undef)
+  $x->precision($n);	 # set P of $x to $n
+  $x->accuracy();	 # return A of $x (or global, if A of $x undef)
+  $x->accuracy($n);	 # set A $x to $n
 
   # Global methods
-  Math::BigInt->precision();	# get/set global P for all BigInt objects
-  Math::BigInt->accuracy(); 	# get/set global A for all BigInt objects
-  Math::BigInt->round_mode();	# get/set global round mode, one of
-				# 'even', 'odd', '+inf', '-inf', 'zero', 'trunc' or 'common'
-  Math::BigInt->config();	# return hash containing configuration
+  Math::BigInt->precision();   # get/set global P for all BigInt objects
+  Math::BigInt->accuracy();    # get/set global A for all BigInt objects
+  Math::BigInt->round_mode();  # get/set global round mode, one of
+			       # 'even', 'odd', '+inf', '-inf', 'zero',
+			       # 'trunc' or 'common'
+  Math::BigInt->config();      # return hash containing configuration
 
 =head1 DESCRIPTION
 
@@ -3527,33 +3533,33 @@ Returns a hash containing the configuration, e.g. the version number, lib
 loaded etc. The following hash keys are currently filled in with the
 appropriate information.
 
-	key		Description
-			Example
+	key	      Description
+		      Example
 	============================================================
-	lib		Name of the low-level math library
-			Math::BigInt::Calc
-	lib_version 	Version of low-level math library (see 'lib')
-			0.30
-	class		The class name of config() you just called
-			Math::BigInt
-	upgrade		To which class math operations might be upgraded
-			Math::BigFloat
-	downgrade	To which class math operations might be downgraded
-			undef
-	precision	Global precision
-			undef
-	accuracy	Global accuracy
-			undef
-	round_mode	Global round mode
-			even
-	version		version number of the class you used
-			1.61
-	div_scale	Fallback accuracy for div
-			40
-	trap_nan	If true, traps creation of NaN via croak()
-			1
-	trap_inf	If true, traps creation of +inf/-inf via croak()
-			1
+	lib	      Name of the low-level math library
+		      Math::BigInt::Calc
+	lib_version   Version of low-level math library (see 'lib')
+		      0.30
+	class	      The class name of config() you just called
+		      Math::BigInt
+	upgrade	      To which class math operations might be upgraded
+		      Math::BigFloat
+	downgrade     To which class math operations might be downgraded
+		      undef
+	precision     Global precision
+		      undef
+	accuracy      Global accuracy
+		      undef
+	round_mode    Global round mode
+		      even
+	version	      version number of the class you used
+		      1.61
+	div_scale     Fallback accuracy for div
+		      40
+	trap_nan      If true, traps creation of NaN via croak()
+		      1
+	trap_inf      If true, traps creation of +inf/-inf via croak()
+		      1
 
 The following values can be set by passing C<config()> a reference to a hash:
 
@@ -3562,16 +3568,18 @@ The following values can be set by passing C<config()> a reference to a hash:
 
 Example:
 
-	$new_cfg = Math::BigInt->config( { trap_inf => 1, precision => 5 } );
+	$new_cfg = Math::BigInt->config(
+	    { trap_inf => 1, precision => 5 }
+	);
 
 =head2 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()!
@@ -3584,31 +3592,32 @@ In most cases, you should probably round the results explicitly using one of
 L<round()>, L<bround()> or L<bfround()> or by passing the desired accuracy
 to the math operation as additional parameter:
 
-        my $x = Math::BigInt->new(30000);
-        my $y = Math::BigInt->new(7);
-        print scalar $x->copy()->bdiv($y, 2);		# print 4300
-        print scalar $x->copy()->bdiv($y)->bround(2);	# print 4300
+    my $x = Math::BigInt->new(30000);
+    my $y = Math::BigInt->new(7);
+    print scalar $x->copy()->bdiv($y, 2);		# print 4300
+    print scalar $x->copy()->bdiv($y)->bround(2);	# print 4300
 
 Please see the section about L<ACCURACY and PRECISION> for further details.
 
 Value must be greater than zero. Pass an undef value to disable it:
 
-	$x->accuracy(undef);
-	Math::BigInt->accuracy(undef);
+    $x->accuracy(undef);
+    Math::BigInt->accuracy(undef);
 
 Returns the current accuracy. For C<< $x->accuracy() >> it will return either
 the local accuracy, or if not defined, the global. This means the return value
 represents the accuracy that will be in effect for $x:
 
-	$y = Math::BigInt->new(1234567);	# unrounded
-	print Math::BigInt->accuracy(4),"\n";	# set 4, print 4
-	$x = Math::BigInt->new(123456);		# $x will be automatically rounded!
-	print "$x $y\n";			# '123500 1234567'
-	print $x->accuracy(),"\n";		# will be 4
-	print $y->accuracy(),"\n";		# also 4, since global is 4
-	print Math::BigInt->accuracy(5),"\n";	# set to 5, print 5
-	print $x->accuracy(),"\n";		# still 4
-	print $y->accuracy(),"\n";		# 5, since global is 5
+    $y = Math::BigInt->new(1234567);	   # unrounded
+    print Math::BigInt->accuracy(4),"\n";  # set 4, print 4
+    $x = Math::BigInt->new(123456);	   # $x will be automatic-
+					   # ally rounded!
+    print "$x $y\n";			   # '123500 1234567'
+    print $x->accuracy(),"\n";		   # will be 4
+    print $y->accuracy(),"\n";		   # also 4, since global is 4
+    print Math::BigInt->accuracy(5),"\n";  # set to 5, print 5
+    print $x->accuracy(),"\n";		   # still 4
+    print $y->accuracy(),"\n";		   # 5, since global is 5
 
 Note: Works also for subclasses like Math::BigFloat. Each class has it's own
 globals separated from Math::BigInt, but it is possible to subclass
@@ -3617,15 +3626,17 @@ Math::BigInt.
 
 =head2 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
@@ -3643,17 +3654,17 @@ Please see the section about L<ACCURACY and PRECISION> for further details.
 
 Pass an undef value to disable it:
 
-	$x->precision(undef);
-	Math::BigInt->precision(undef);
+    $x->precision(undef);
+    Math::BigInt->precision(undef);
 
 Returns the current precision. For C<< $x->precision() >> it will return either
 the local precision of $x, or if not defined, the global. This means the return
 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
-	print $x;				# print "120000"!
+    $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
+    print $x;				    # print "120000"!
 
 Note: Works also for subclasses like L<Math::BigFloat>. Each class has its
 own globals separated from Math::BigInt, but it is possible to subclass
@@ -3762,12 +3773,12 @@ If used on an object, it will set it to one:
 
 =head2 is_one()/is_zero()/is_nan()/is_inf()
 
-	$x->is_zero();			# true if arg is +0
-	$x->is_nan();			# true if arg is NaN
-	$x->is_one();			# true if arg is +1
-	$x->is_one('-');		# true if arg is -1
-	$x->is_inf();			# true if +inf
-	$x->is_inf('-');		# true if -inf (sign is default '+')
+	$x->is_zero();		# true if arg is +0
+	$x->is_nan();		# true if arg is NaN
+	$x->is_one();		# true if arg is +1
+	$x->is_one('-');	# true if arg is -1
+	$x->is_inf();		# true if +inf
+	$x->is_inf('-');	# true if -inf (sign is default '+')
 
 These methods all test the BigInt for being one specific value and return
 true or false depending on the input. These are faster than doing something
@@ -3831,7 +3842,7 @@ If you want $x to have a certain sign, use one of the following methods:
 
 =head2 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.
 
@@ -3866,23 +3877,23 @@ but faster.
 
 =head2 binc()
 
-	$x->binc();			# increment x by 1
+	$x->binc();		# increment x by 1
 
 =head2 bdec()
 
-	$x->bdec();			# decrement x by 1
+	$x->bdec();		# decrement x by 1
 
 =head2 badd()
 
-	$x->badd($y);			# addition (add $y to $x)
+	$x->badd($y);		# addition (add $y to $x)
 
 =head2 bsub()
 
-	$x->bsub($y);			# subtraction (subtract $y from $x)
+	$x->bsub($y);		# subtraction (subtract $y from $x)
 
 =head2 bmul()
 
-	$x->bmul($y);			# multiplication (multiply $x by $y)
+	$x->bmul($y);		# multiplication (multiply $x by $y)
 
 =head2 bmuladd()
 
@@ -3894,16 +3905,16 @@ This method was added in v1.87 of Math::BigInt (June 2007).
 
 =head2 bdiv()
 
-	$x->bdiv($y);			# divide, set $x to quotient
-					# return (quo,rem) or quo if scalar
+	$x->bdiv($y);		# divide, set $x to quotient
+				# return (quo,rem) or quo if scalar
 
 =head2 bmod()
 
-	$x->bmod($y);			# modulus (x % y)
+	$x->bmod($y);		# modulus (x % y)
 
 =head2 bmodinv()
 
-	$x->bmodinv($mod);		# modular multiplicative inverse
+	$x->bmodinv($mod);	# modular multiplicative inverse
 
 Returns the multiplicative inverse of C<$x> modulo C<$mod>. If
 
@@ -3942,19 +3953,19 @@ is exactly equivalent to
 
 =head2 bpow()
 
-	$x->bpow($y);			# power of arguments (x ** y)
+	$x->bpow($y);		      # power of arguments (x ** y)
 
 =head2 blog()
 
-	$x->blog($base, $accuracy);	# logarithm of x to the base $base
+	$x->blog($base, $accuracy);   # logarithm of x to the base $base
 
 If C<$base> is not defined, Euler's number (e) is used:
 
-	print $x->blog(undef, 100);	# log(x) to 100 digits
+	print $x->blog(undef, 100);   # log(x) to 100 digits
 
 =head2 bexp()
 
-	$x->bexp($accuracy);		# calculate e ** X
+	$x->bexp($accuracy);	      # calculate e ** X
 
 Calculates the expression C<e ** $x> where C<e> is Euler's number.
 
@@ -3964,7 +3975,7 @@ See also L<blog()>.
 
 =head2 bnok()
 
-	$x->bnok($y);		   # x over y (binomial coefficient n over k)
+	$x->bnok($y);	     # x over y (binomial coefficient n over k)
 
 Calculates the binomial coefficient n over k, also called the "choose"
 function. The result is equivalent to:
@@ -4154,11 +4165,11 @@ Return the signed mantissa of $x as BigInt.
 
 =head2 parts()
 
-	$x->parts();		# return (mantissa,exponent) as BigInt
+	$x->parts();	# return (mantissa,exponent) as BigInt
 
 =head2 copy()
 
-	$x->copy();		# make a true copy of $x (unlike $y = $x;)
+	$x->copy();	# make a true copy of $x (unlike $y = $x;)
 
 =head2 as_int()/as_number()
 
@@ -4178,19 +4189,19 @@ Returns a normalized string representation of C<$x>.
 
 =head2 bsstr()
 
-	$x->bsstr();		# normalized string in scientific notation
+	$x->bsstr();	# normalized string in scientific notation
 
 =head2 as_hex()
 
-	$x->as_hex();		# as signed hexadecimal string with prefixed 0x
+	$x->as_hex();	# as signed hexadecimal string with prefixed 0x
 
 =head2 as_bin()
 
-	$x->as_bin();		# as signed binary string with prefixed 0b
+	$x->as_bin();	# as signed binary string with prefixed 0b
 
 =head2 as_oct()
 
-	$x->as_oct();		# as signed octal string with prefixed 0
+	$x->as_oct();	# as signed octal string with prefixed 0
 
 =head2 numify()