Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 666 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man3pm/Math::Complex.3pm b/upstream/mageia-cauldron/man3pm/Math::Complex.3pm
new file mode 100644
index 00000000..7cd480af
--- /dev/null
+++ b/upstream/mageia-cauldron/man3pm/Math::Complex.3pm
@@ -0,0 +1,666 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "Math::Complex 3pm"
+.TH Math::Complex 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH NAME
+Math::Complex \- complex numbers and associated mathematical functions
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\&        use Math::Complex;
+\&
+\&        $z = Math::Complex\->make(5, 6);
+\&        $t = 4 \- 3*i + $z;
+\&        $j = cplxe(1, 2*pi/3);
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This package lets you create and manipulate complex numbers. By default,
+\&\fIPerl\fR limits itself to real numbers, but an extra \f(CW\*(C`use\*(C'\fR statement brings
+full complex support, along with a full set of mathematical functions
+typically associated with and/or extended to complex numbers.
+.PP
+If you wonder what complex numbers are, they were invented to be able to solve
+the following equation:
+.PP
+.Vb 1
+\&        x*x = \-1
+.Ve
+.PP
+and by definition, the solution is noted \fIi\fR (engineers use \fIj\fR instead since
+\&\fIi\fR usually denotes an intensity, but the name does not matter). The number
+\&\fIi\fR is a pure \fIimaginary\fR number.
+.PP
+The arithmetics with pure imaginary numbers works just like you would expect
+it with real numbers... you just have to remember that
+.PP
+.Vb 1
+\&        i*i = \-1
+.Ve
+.PP
+so you have:
+.PP
+.Vb 5
+\&        5i + 7i = i * (5 + 7) = 12i
+\&        4i \- 3i = i * (4 \- 3) = i
+\&        4i * 2i = \-8
+\&        6i / 2i = 3
+\&        1 / i = \-i
+.Ve
+.PP
+Complex numbers are numbers that have both a real part and an imaginary
+part, and are usually noted:
+.PP
+.Vb 1
+\&        a + bi
+.Ve
+.PP
+where \f(CW\*(C`a\*(C'\fR is the \fIreal\fR part and \f(CW\*(C`b\*(C'\fR is the \fIimaginary\fR part. The
+arithmetic with complex numbers is straightforward. You have to
+keep track of the real and the imaginary parts, but otherwise the
+rules used for real numbers just apply:
+.PP
+.Vb 2
+\&        (4 + 3i) + (5 \- 2i) = (4 + 5) + i(3 \- 2) = 9 + i
+\&        (2 + i) * (4 \- i) = 2*4 + 4i \-2i \-i*i = 8 + 2i + 1 = 9 + 2i
+.Ve
+.PP
+A graphical representation of complex numbers is possible in a plane
+(also called the \fIcomplex plane\fR, but it's really a 2D plane).
+The number
+.PP
+.Vb 1
+\&        z = a + bi
+.Ve
+.PP
+is the point whose coordinates are (a, b). Actually, it would
+be the vector originating from (0, 0) to (a, b). It follows that the addition
+of two complex numbers is a vectorial addition.
+.PP
+Since there is a bijection between a point in the 2D plane and a complex
+number (i.e. the mapping is unique and reciprocal), a complex number
+can also be uniquely identified with polar coordinates:
+.PP
+.Vb 1
+\&        [rho, theta]
+.Ve
+.PP
+where \f(CW\*(C`rho\*(C'\fR is the distance to the origin, and \f(CW\*(C`theta\*(C'\fR the angle between
+the vector and the \fIx\fR axis. There is a notation for this using the
+exponential form, which is:
+.PP
+.Vb 1
+\&        rho * exp(i * theta)
+.Ve
+.PP
+where \fIi\fR is the famous imaginary number introduced above. Conversion
+between this form and the cartesian form \f(CW\*(C`a + bi\*(C'\fR is immediate:
+.PP
+.Vb 2
+\&        a = rho * cos(theta)
+\&        b = rho * sin(theta)
+.Ve
+.PP
+which is also expressed by this formula:
+.PP
+.Vb 1
+\&        z = rho * exp(i * theta) = rho * (cos theta + i * sin theta)
+.Ve
+.PP
+In other words, it's the projection of the vector onto the \fIx\fR and \fIy\fR
+axes. Mathematicians call \fIrho\fR the \fInorm\fR or \fImodulus\fR and \fItheta\fR
+the \fIargument\fR of the complex number. The \fInorm\fR of \f(CW\*(C`z\*(C'\fR is
+marked here as \f(CWabs(z)\fR.
+.PP
+The polar notation (also known as the trigonometric representation) is
+much more handy for performing multiplications and divisions of
+complex numbers, whilst the cartesian notation is better suited for
+additions and subtractions. Real numbers are on the \fIx\fR axis, and
+therefore \fIy\fR or \fItheta\fR is zero or \fIpi\fR.
+.PP
+All the common operations that can be performed on a real number have
+been defined to work on complex numbers as well, and are merely
+\&\fIextensions\fR of the operations defined on real numbers. This means
+they keep their natural meaning when there is no imaginary part, provided
+the number is within their definition set.
+.PP
+For instance, the \f(CW\*(C`sqrt\*(C'\fR routine which computes the square root of
+its argument is only defined for non-negative real numbers and yields a
+non-negative real number (it is an application from \fBR+\fR to \fBR+\fR).
+If we allow it to return a complex number, then it can be extended to
+negative real numbers to become an application from \fBR\fR to \fBC\fR (the
+set of complex numbers):
+.PP
+.Vb 1
+\&        sqrt(x) = x >= 0 ? sqrt(x) : sqrt(\-x)*i
+.Ve
+.PP
+It can also be extended to be an application from \fBC\fR to \fBC\fR,
+whilst its restriction to \fBR\fR behaves as defined above by using
+the following definition:
+.PP
+.Vb 1
+\&        sqrt(z = [r,t]) = sqrt(r) * exp(i * t/2)
+.Ve
+.PP
+Indeed, a negative real number can be noted \f(CW\*(C`[x,pi]\*(C'\fR (the modulus
+\&\fIx\fR is always non-negative, so \f(CW\*(C`[x,pi]\*(C'\fR is really \f(CW\*(C`\-x\*(C'\fR, a negative
+number) and the above definition states that
+.PP
+.Vb 1
+\&        sqrt([x,pi]) = sqrt(x) * exp(i*pi/2) = [sqrt(x),pi/2] = sqrt(x)*i
+.Ve
+.PP
+which is exactly what we had defined for negative real numbers above.
+The \f(CW\*(C`sqrt\*(C'\fR returns only one of the solutions: if you want the both,
+use the \f(CW\*(C`root\*(C'\fR function.
+.PP
+All the common mathematical functions defined on real numbers that
+are extended to complex numbers share that same property of working
+\&\fIas usual\fR when the imaginary part is zero (otherwise, it would not
+be called an extension, would it?).
+.PP
+A \fInew\fR operation possible on a complex number that is
+the identity for real numbers is called the \fIconjugate\fR, and is noted
+with a horizontal bar above the number, or \f(CW\*(C`~z\*(C'\fR here.
+.PP
+.Vb 2
+\&         z = a + bi
+\&        ~z = a \- bi
+.Ve
+.PP
+Simple... Now look:
+.PP
+.Vb 1
+\&        z * ~z = (a + bi) * (a \- bi) = a*a + b*b
+.Ve
+.PP
+We saw that the norm of \f(CW\*(C`z\*(C'\fR was noted \f(CWabs(z)\fR and was defined as the
+distance to the origin, also known as:
+.PP
+.Vb 1
+\&        rho = abs(z) = sqrt(a*a + b*b)
+.Ve
+.PP
+so
+.PP
+.Vb 1
+\&        z * ~z = abs(z) ** 2
+.Ve
+.PP
+If z is a pure real number (i.e. \f(CW\*(C`b == 0\*(C'\fR), then the above yields:
+.PP
+.Vb 1
+\&        a * a = abs(a) ** 2
+.Ve
+.PP
+which is true (\f(CW\*(C`abs\*(C'\fR has the regular meaning for real number, i.e. stands
+for the absolute value). This example explains why the norm of \f(CW\*(C`z\*(C'\fR is
+noted \f(CWabs(z)\fR: it extends the \f(CW\*(C`abs\*(C'\fR function to complex numbers, yet
+is the regular \f(CW\*(C`abs\*(C'\fR we know when the complex number actually has no
+imaginary part... This justifies \fIa posteriori\fR our use of the \f(CW\*(C`abs\*(C'\fR
+notation for the norm.
+.SH OPERATIONS
+.IX Header "OPERATIONS"
+Given the following notations:
+.PP
+.Vb 3
+\&        z1 = a + bi = r1 * exp(i * t1)
+\&        z2 = c + di = r2 * exp(i * t2)
+\&        z = <any complex or real number>
+.Ve
+.PP
+the following (overloaded) operations are supported on complex numbers:
+.PP
+.Vb 10
+\&        z1 + z2 = (a + c) + i(b + d)
+\&        z1 \- z2 = (a \- c) + i(b \- d)
+\&        z1 * z2 = (r1 * r2) * exp(i * (t1 + t2))
+\&        z1 / z2 = (r1 / r2) * exp(i * (t1 \- t2))
+\&        z1 ** z2 = exp(z2 * log z1)
+\&        ~z = a \- bi
+\&        abs(z) = r1 = sqrt(a*a + b*b)
+\&        sqrt(z) = sqrt(r1) * exp(i * t/2)
+\&        exp(z) = exp(a) * exp(i * b)
+\&        log(z) = log(r1) + i*t
+\&        sin(z) = 1/2i (exp(i * z1) \- exp(\-i * z))
+\&        cos(z) = 1/2 (exp(i * z1) + exp(\-i * z))
+\&        atan2(y, x) = atan(y / x) # Minding the right quadrant, note the order.
+.Ve
+.PP
+The definition used for complex arguments of \fBatan2()\fR is
+.PP
+.Vb 1
+\&       \-i log((x + iy)/sqrt(x*x+y*y))
+.Ve
+.PP
+Note that atan2(0, 0) is not well-defined.
+.PP
+The following extra operations are supported on both real and complex
+numbers:
+.PP
+.Vb 4
+\&        Re(z) = a
+\&        Im(z) = b
+\&        arg(z) = t
+\&        abs(z) = r
+\&
+\&        cbrt(z) = z ** (1/3)
+\&        log10(z) = log(z) / log(10)
+\&        logn(z, n) = log(z) / log(n)
+\&
+\&        tan(z) = sin(z) / cos(z)
+\&
+\&        csc(z) = 1 / sin(z)
+\&        sec(z) = 1 / cos(z)
+\&        cot(z) = 1 / tan(z)
+\&
+\&        asin(z) = \-i * log(i*z + sqrt(1\-z*z))
+\&        acos(z) = \-i * log(z + i*sqrt(1\-z*z))
+\&        atan(z) = i/2 * log((i+z) / (i\-z))
+\&
+\&        acsc(z) = asin(1 / z)
+\&        asec(z) = acos(1 / z)
+\&        acot(z) = atan(1 / z) = \-i/2 * log((i+z) / (z\-i))
+\&
+\&        sinh(z) = 1/2 (exp(z) \- exp(\-z))
+\&        cosh(z) = 1/2 (exp(z) + exp(\-z))
+\&        tanh(z) = sinh(z) / cosh(z) = (exp(z) \- exp(\-z)) / (exp(z) + exp(\-z))
+\&
+\&        csch(z) = 1 / sinh(z)
+\&        sech(z) = 1 / cosh(z)
+\&        coth(z) = 1 / tanh(z)
+\&
+\&        asinh(z) = log(z + sqrt(z*z+1))
+\&        acosh(z) = log(z + sqrt(z*z\-1))
+\&        atanh(z) = 1/2 * log((1+z) / (1\-z))
+\&
+\&        acsch(z) = asinh(1 / z)
+\&        asech(z) = acosh(1 / z)
+\&        acoth(z) = atanh(1 / z) = 1/2 * log((1+z) / (z\-1))
+.Ve
+.PP
+\&\fIarg\fR, \fIabs\fR, \fIlog\fR, \fIcsc\fR, \fIcot\fR, \fIacsc\fR, \fIacot\fR, \fIcsch\fR,
+\&\fIcoth\fR, \fIacosech\fR, \fIacotanh\fR, have aliases \fIrho\fR, \fItheta\fR, \fIln\fR,
+\&\fIcosec\fR, \fIcotan\fR, \fIacosec\fR, \fIacotan\fR, \fIcosech\fR, \fIcotanh\fR,
+\&\fIacosech\fR, \fIacotanh\fR, respectively.  \f(CW\*(C`Re\*(C'\fR, \f(CW\*(C`Im\*(C'\fR, \f(CW\*(C`arg\*(C'\fR, \f(CW\*(C`abs\*(C'\fR,
+\&\f(CW\*(C`rho\*(C'\fR, and \f(CW\*(C`theta\*(C'\fR can be used also as mutators.  The \f(CW\*(C`cbrt\*(C'\fR
+returns only one of the solutions: if you want all three, use the
+\&\f(CW\*(C`root\*(C'\fR function.
+.PP
+The \fIroot\fR function is available to compute all the \fIn\fR
+roots of some complex, where \fIn\fR is a strictly positive integer.
+There are exactly \fIn\fR such roots, returned as a list. Getting the
+number mathematicians call \f(CW\*(C`j\*(C'\fR such that:
+.PP
+.Vb 1
+\&        1 + j + j*j = 0;
+.Ve
+.PP
+is a simple matter of writing:
+.PP
+.Vb 1
+\&        $j = (root(1, 3))[1];
+.Ve
+.PP
+The \fIk\fRth root for \f(CW\*(C`z = [r,t]\*(C'\fR is given by:
+.PP
+.Vb 1
+\&        (root(z, n))[k] = r**(1/n) * exp(i * (t + 2*k*pi)/n)
+.Ve
+.PP
+You can return the \fIk\fRth root directly by \f(CW\*(C`root(z, n, k)\*(C'\fR,
+indexing starting from \fIzero\fR and ending at \fIn \- 1\fR.
+.PP
+The \fIspaceship\fR numeric comparison operator, <=>, is also
+defined. In order to ensure its restriction to real numbers is conform
+to what you would expect, the comparison is run on the real part of
+the complex number first, and imaginary parts are compared only when
+the real parts match.
+.SH CREATION
+.IX Header "CREATION"
+To create a complex number, use either:
+.PP
+.Vb 2
+\&        $z = Math::Complex\->make(3, 4);
+\&        $z = cplx(3, 4);
+.Ve
+.PP
+if you know the cartesian form of the number, or
+.PP
+.Vb 1
+\&        $z = 3 + 4*i;
+.Ve
+.PP
+if you like. To create a number using the polar form, use either:
+.PP
+.Vb 2
+\&        $z = Math::Complex\->emake(5, pi/3);
+\&        $x = cplxe(5, pi/3);
+.Ve
+.PP
+instead. The first argument is the modulus, the second is the angle
+(in radians, the full circle is 2*pi).  (Mnemonic: \f(CW\*(C`e\*(C'\fR is used as a
+notation for complex numbers in the polar form).
+.PP
+It is possible to write:
+.PP
+.Vb 1
+\&        $x = cplxe(\-3, pi/4);
+.Ve
+.PP
+but that will be silently converted into \f(CW\*(C`[3,\-3pi/4]\*(C'\fR, since the
+modulus must be non-negative (it represents the distance to the origin
+in the complex plane).
+.PP
+It is also possible to have a complex number as either argument of the
+\&\f(CW\*(C`make\*(C'\fR, \f(CW\*(C`emake\*(C'\fR, \f(CW\*(C`cplx\*(C'\fR, and \f(CW\*(C`cplxe\*(C'\fR: the appropriate component of
+the argument will be used.
+.PP
+.Vb 2
+\&        $z1 = cplx(\-2,  1);
+\&        $z2 = cplx($z1, 4);
+.Ve
+.PP
+The \f(CW\*(C`new\*(C'\fR, \f(CW\*(C`make\*(C'\fR, \f(CW\*(C`emake\*(C'\fR, \f(CW\*(C`cplx\*(C'\fR, and \f(CW\*(C`cplxe\*(C'\fR will also
+understand a single (string) argument of the forms
+.PP
+.Vb 5
+\&        2\-3i
+\&        \-3i
+\&        [2,3]
+\&        [2,\-3pi/4]
+\&        [2]
+.Ve
+.PP
+in which case the appropriate cartesian and exponential components
+will be parsed from the string and used to create new complex numbers.
+The imaginary component and the theta, respectively, will default to zero.
+.PP
+The \f(CW\*(C`new\*(C'\fR, \f(CW\*(C`make\*(C'\fR, \f(CW\*(C`emake\*(C'\fR, \f(CW\*(C`cplx\*(C'\fR, and \f(CW\*(C`cplxe\*(C'\fR will also
+understand the case of no arguments: this means plain zero or (0, 0).
+.SH DISPLAYING
+.IX Header "DISPLAYING"
+When printed, a complex number is usually shown under its cartesian
+style \fIa+bi\fR, but there are legitimate cases where the polar style
+\&\fI[r,t]\fR is more appropriate.  The process of converting the complex
+number into a string that can be displayed is known as \fIstringification\fR.
+.PP
+By calling the class method \f(CW\*(C`Math::Complex::display_format\*(C'\fR and
+supplying either \f(CW"polar"\fR or \f(CW"cartesian"\fR as an argument, you
+override the default display style, which is \f(CW"cartesian"\fR. Not
+supplying any argument returns the current settings.
+.PP
+This default can be overridden on a per-number basis by calling the
+\&\f(CW\*(C`display_format\*(C'\fR method instead. As before, not supplying any argument
+returns the current display style for this number. Otherwise whatever you
+specify will be the new display style for \fIthis\fR particular number.
+.PP
+For instance:
+.PP
+.Vb 1
+\&        use Math::Complex;
+\&
+\&        Math::Complex::display_format(\*(Aqpolar\*(Aq);
+\&        $j = (root(1, 3))[1];
+\&        print "j = $j\en";               # Prints "j = [1,2pi/3]"
+\&        $j\->display_format(\*(Aqcartesian\*(Aq);
+\&        print "j = $j\en";               # Prints "j = \-0.5+0.866025403784439i"
+.Ve
+.PP
+The polar style attempts to emphasize arguments like \fIk*pi/n\fR
+(where \fIn\fR is a positive integer and \fIk\fR an integer within [\-9, +9]),
+this is called \fIpolar pretty-printing\fR.
+.PP
+For the reverse of stringifying, see the \f(CW\*(C`make\*(C'\fR and \f(CW\*(C`emake\*(C'\fR.
+.SS "CHANGED IN PERL 5.6"
+.IX Subsection "CHANGED IN PERL 5.6"
+The \f(CW\*(C`display_format\*(C'\fR class method and the corresponding
+\&\f(CW\*(C`display_format\*(C'\fR object method can now be called using
+a parameter hash instead of just a one parameter.
+.PP
+The old display format style, which can have values \f(CW"cartesian"\fR or
+\&\f(CW"polar"\fR, can be changed using the \f(CW"style"\fR parameter.
+.PP
+.Vb 1
+\&        $j\->display_format(style => "polar");
+.Ve
+.PP
+The one parameter calling convention also still works.
+.PP
+.Vb 1
+\&        $j\->display_format("polar");
+.Ve
+.PP
+There are two new display parameters.
+.PP
+The first one is \f(CW"format"\fR, which is a \fBsprintf()\fR\-style format string
+to be used for both numeric parts of the complex number(s).  The is
+somewhat system-dependent but most often it corresponds to \f(CW"%.15g"\fR.
+You can revert to the default by setting the \f(CW\*(C`format\*(C'\fR to \f(CW\*(C`undef\*(C'\fR.
+.PP
+.Vb 1
+\&        # the $j from the above example
+\&
+\&        $j\->display_format(\*(Aqformat\*(Aq => \*(Aq%.5f\*(Aq);
+\&        print "j = $j\en";               # Prints "j = \-0.50000+0.86603i"
+\&        $j\->display_format(\*(Aqformat\*(Aq => undef);
+\&        print "j = $j\en";               # Prints "j = \-0.5+0.86603i"
+.Ve
+.PP
+Notice that this affects also the return values of the
+\&\f(CW\*(C`display_format\*(C'\fR methods: in list context the whole parameter hash
+will be returned, as opposed to only the style parameter value.
+This is a potential incompatibility with earlier versions if you
+have been calling the \f(CW\*(C`display_format\*(C'\fR method in list context.
+.PP
+The second new display parameter is \f(CW"polar_pretty_print"\fR, which can
+be set to true or false, the default being true.  See the previous
+section for what this means.
+.SH USAGE
+.IX Header "USAGE"
+Thanks to overloading, the handling of arithmetics with complex numbers
+is simple and almost transparent.
+.PP
+Here are some examples:
+.PP
+.Vb 1
+\&        use Math::Complex;
+\&
+\&        $j = cplxe(1, 2*pi/3);  # $j ** 3 == 1
+\&        print "j = $j, j**3 = ", $j ** 3, "\en";
+\&        print "1 + j + j**2 = ", 1 + $j + $j**2, "\en";
+\&
+\&        $z = \-16 + 0*i;                 # Force it to be a complex
+\&        print "sqrt($z) = ", sqrt($z), "\en";
+\&
+\&        $k = exp(i * 2*pi/3);
+\&        print "$j \- $k = ", $j \- $k, "\en";
+\&
+\&        $z\->Re(3);                      # Re, Im, arg, abs,
+\&        $j\->arg(2);                     # (the last two aka rho, theta)
+\&                                        # can be used also as mutators.
+.Ve
+.SH CONSTANTS
+.IX Header "CONSTANTS"
+.SS PI
+.IX Subsection "PI"
+The constant \f(CW\*(C`pi\*(C'\fR and some handy multiples of it (pi2, pi4,
+and pip2 (pi/2) and pip4 (pi/4)) are also available if separately
+exported:
+.PP
+.Vb 2
+\&    use Math::Complex \*(Aq:pi\*(Aq; 
+\&    $third_of_circle = pi2 / 3;
+.Ve
+.SS Inf
+.IX Subsection "Inf"
+The floating point infinity can be exported as a subroutine \fBInf()\fR:
+.PP
+.Vb 4
+\&    use Math::Complex qw(Inf sinh);
+\&    my $AlsoInf = Inf() + 42;
+\&    my $AnotherInf = sinh(1e42);
+\&    print "$AlsoInf is $AnotherInf\en" if $AlsoInf == $AnotherInf;
+.Ve
+.PP
+Note that the stringified form of infinity varies between platforms:
+it can be for example any of
+.PP
+.Vb 4
+\&   inf
+\&   infinity
+\&   INF
+\&   1.#INF
+.Ve
+.PP
+or it can be something else.
+.PP
+Also note that in some platforms trying to use the infinity in
+arithmetic operations may result in Perl crashing because using
+an infinity causes SIGFPE or its moral equivalent to be sent.
+The way to ignore this is
+.PP
+.Vb 1
+\&  local $SIG{FPE} = sub { };
+.Ve
+.SH "ERRORS DUE TO DIVISION BY ZERO OR LOGARITHM OF ZERO"
+.IX Header "ERRORS DUE TO DIVISION BY ZERO OR LOGARITHM OF ZERO"
+The division (/) and the following functions
+.PP
+.Vb 5
+\&        log     ln      log10   logn
+\&        tan     sec     csc     cot
+\&        atan    asec    acsc    acot
+\&        tanh    sech    csch    coth
+\&        atanh   asech   acsch   acoth
+.Ve
+.PP
+cannot be computed for all arguments because that would mean dividing
+by zero or taking logarithm of zero. These situations cause fatal
+runtime errors looking like this
+.PP
+.Vb 3
+\&        cot(0): Division by zero.
+\&        (Because in the definition of cot(0), the divisor sin(0) is 0)
+\&        Died at ...
+.Ve
+.PP
+or
+.PP
+.Vb 2
+\&        atanh(\-1): Logarithm of zero.
+\&        Died at...
+.Ve
+.PP
+For the \f(CW\*(C`csc\*(C'\fR, \f(CW\*(C`cot\*(C'\fR, \f(CW\*(C`asec\*(C'\fR, \f(CW\*(C`acsc\*(C'\fR, \f(CW\*(C`acot\*(C'\fR, \f(CW\*(C`csch\*(C'\fR, \f(CW\*(C`coth\*(C'\fR,
+\&\f(CW\*(C`asech\*(C'\fR, \f(CW\*(C`acsch\*(C'\fR, the argument cannot be \f(CW0\fR (zero).  For the
+logarithmic functions and the \f(CW\*(C`atanh\*(C'\fR, \f(CW\*(C`acoth\*(C'\fR, the argument cannot
+be \f(CW1\fR (one).  For the \f(CW\*(C`atanh\*(C'\fR, \f(CW\*(C`acoth\*(C'\fR, the argument cannot be
+\&\f(CW\-1\fR (minus one).  For the \f(CW\*(C`atan\*(C'\fR, \f(CW\*(C`acot\*(C'\fR, the argument cannot be
+\&\f(CW\*(C`i\*(C'\fR (the imaginary unit).  For the \f(CW\*(C`atan\*(C'\fR, \f(CW\*(C`acoth\*(C'\fR, the argument
+cannot be \f(CW\*(C`\-i\*(C'\fR (the negative imaginary unit).  For the \f(CW\*(C`tan\*(C'\fR,
+\&\f(CW\*(C`sec\*(C'\fR, \f(CW\*(C`tanh\*(C'\fR, the argument cannot be \fIpi/2 + k * pi\fR, where \fIk\fR
+is any integer.  atan2(0, 0) is undefined, and if the complex arguments
+are used for \fBatan2()\fR, a division by zero will happen if z1**2+z2**2 == 0.
+.PP
+Note that because we are operating on approximations of real numbers,
+these errors can happen when merely `too close' to the singularities
+listed above.
+.SH "ERRORS DUE TO INDIGESTIBLE ARGUMENTS"
+.IX Header "ERRORS DUE TO INDIGESTIBLE ARGUMENTS"
+The \f(CW\*(C`make\*(C'\fR and \f(CW\*(C`emake\*(C'\fR accept both real and complex arguments.
+When they cannot recognize the arguments they will die with error
+messages like the following
+.PP
+.Vb 4
+\&    Math::Complex::make: Cannot take real part of ...
+\&    Math::Complex::make: Cannot take real part of ...
+\&    Math::Complex::emake: Cannot take rho of ...
+\&    Math::Complex::emake: Cannot take theta of ...
+.Ve
+.SH BUGS
+.IX Header "BUGS"
+Saying \f(CW\*(C`use Math::Complex;\*(C'\fR exports many mathematical routines in the
+caller environment and even overrides some (\f(CW\*(C`sqrt\*(C'\fR, \f(CW\*(C`log\*(C'\fR, \f(CW\*(C`atan2\*(C'\fR).
+This is construed as a feature by the Authors, actually... ;\-)
+.PP
+All routines expect to be given real or complex numbers. Don't attempt to
+use BigFloat, since Perl has currently no rule to disambiguate a '+'
+operation (for instance) between two overloaded entities.
+.PP
+In Cray UNICOS there is some strange numerical instability that results
+in \fBroot()\fR, \fBcos()\fR, \fBsin()\fR, \fBcosh()\fR, \fBsinh()\fR, losing accuracy fast.  Beware.
+The bug may be in UNICOS math libs, in UNICOS C compiler, in Math::Complex.
+Whatever it is, it does not manifest itself anywhere else where Perl runs.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Math::Trig
+.SH AUTHORS
+.IX Header "AUTHORS"
+Daniel S. Lewart <\fIlewart!at!uiuc.edu\fR>,
+Jarkko Hietaniemi <\fIjhi!at!iki.fi\fR>,
+Raphael Manfredi <\fIRaphael_Manfredi!at!pobox.com\fR>,
+Zefram <zefram@fysh.org>
+.SH LICENSE
+.IX Header "LICENSE"
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.