Re: expm1(3p): Mathematical error in given example

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

On 2/12/21 10:41 AM, Jakub Wilk wrote:
> * Alejandro Colomar <alx.manpages@gmail.com>, 2021-02-11, 16:49:
>>> In the APPLICATION USAGE section of expm1(3p)[1] the given example is wrong:
>>>
>>> ===8<=== Snip =========================================
>>>
>>> [..] calculations of ((1+x)n-1)/x, namely:
>>>
>>>           expm1(n * log1p(x))/x
>>>
>>> ======== Snap ====================================>8===
>>>
>>> Actually, both expressions are not equal, rather
>>>
>>> expm1(n * log1p(x))/x = ((1+x)**n - 1)/x
>>>
>>> (with a fictional ** as power infix-operator) would be.
> [...]
>> We don't maintain the source of the POSIX manual pages.  You could file 
>> a bug to the Austin Group.
> 
> As Walter noted in another mail, the POSIX sources are correct.
> 
> This is a problem with conversion to the man page format, which should 
> be reported here, not to the Austin Group.

Indeed, it is a problem in the conversion. Or, more precisely, the
POSIX manual pages are using \u...\d to achieve superscripting
for exponentiation, which of course does not render meaningfully
on a terminal. The issue affects 19 pages that I found. I plan
to apply the patch below, which uses the fictional '**' operator
to indicate power-of. Seem okay?

Thanks,

Michael

diff --git a/man-pages-posix-2017/man0p/complex.h.0p b/man-pages-posix-2017/man0p/complex.h.0p
index ccc21a7..da37e54 100644
--- a/man-pages-posix-2017/man0p/complex.h.0p
+++ b/man-pages-posix-2017/man0p/complex.h.0p
@@ -31,7 +31,7 @@ Expands to a constant expression of type
 .BR "const float _Complex" ,
 with the value of the imaginary unit (that is, a number
 .IR i
-such that \fIi\fR\s-3\u2\d\s+3=\-1).
+such that \fIi\fR**2=\-1).
 .IP imaginary 12
 Expands to
 .BR _Imaginary .
diff --git a/man-pages-posix-2017/man0p/stdint.h.0p b/man-pages-posix-2017/man0p/stdint.h.0p
index 5acc838..3ccc8cc 100644
--- a/man-pages-posix-2017/man0p/stdint.h.0p
+++ b/man-pages-posix-2017/man0p/stdint.h.0p
@@ -38,11 +38,11 @@ its value in a pure binary system; the actual type may use more bits
 than that (for example, a 28-bit type could be stored in 32 bits of
 actual storage). An
 .IR N -bit
-signed type has values in the range \-2\s-3\u\fIN\fR\-1\d\s+3 or
-1\-2\s-3\u\fIN\fR\-1\d\s+3 to 2\s-3\u\fIN\fR\-1\d\s+3\-1, while
+signed type has values in the range \-2**(\fIN\fR\-1) or
+1\-2**(\fIN\fR\-1) to 2**(\fIN\fR\-1)\-1, while
 an
 .IR N -bit
-unsigned type has values in the range 0 to 2\s-3\u\fIN\fR\d\s+3\-1.
+unsigned type has values in the range 0 to 2**\fIN\fR\-1.
 .P
 .P
 Types are defined in the following categories:
diff --git a/man-pages-posix-2017/man0p/sys_socket.h.0p b/man-pages-posix-2017/man0p/sys_socket.h.0p
index 02b7e4b..bd6e5b4 100644
--- a/man-pages-posix-2017/man0p/sys_socket.h.0p
+++ b/man-pages-posix-2017/man0p/sys_socket.h.0p
@@ -443,7 +443,7 @@ may also make visible all symbols from
 .IR "The following sections are informative."
 .SH "APPLICATION USAGE"
 To forestall portability problems, it is recommended that applications
-not use values larger than 2\u\s-331\s+3\d \-1 for the
+not use values larger than 2**31 \-1 for the
 .BR socklen_t
 type.
 .P
diff --git a/man-pages-posix-2017/man1p/bc.1p b/man-pages-posix-2017/man1p/bc.1p
index fa8bf2e..2beda41 100644
--- a/man-pages-posix-2017/man1p/bc.1p
+++ b/man-pages-posix-2017/man1p/bc.1p
@@ -650,7 +650,7 @@ if
 is less than 10. For
 .BR obase
 values other than 10, this should be the number of digits needed to
-represent a precision of 10\u\s-3\fIs\fP\s+3\d.
+represent a precision of 10**\fIs\fP.
 .P
 For
 .BR obase
diff --git a/man-pages-posix-2017/man1p/cksum.1p b/man-pages-posix-2017/man1p/cksum.1p
index 73ea9b6..2bf2b05 100644
--- a/man-pages-posix-2017/man1p/cksum.1p
+++ b/man-pages-posix-2017/man1p/cksum.1p
@@ -29,7 +29,8 @@ polynomial:
 .RS 4
 .nf
 
-\fIG\fR(\fIx\fR)=\fIx\fR\u\s-332\s+3\d+\fIx\fR\u\s-326\s+3\d+\fIx\fR\u\s-323\s+3\d+\fIx\fR\u\s-322\s+3\d+\fIx\fR\u\s-316\s+3\d+\fIx\fR\u\s-312\s+3\d+\fIx\fR\u\s-311\s+3\d+\fIx\fR\u\s-310\s+3\d+\fIx\fR\u\s-38\s+3\d+\fIx\fR\u\s-37\s+3\d+\fIx\fR\u\s-35\s+3\d+\fIx\fR\u\s-34\s+3\d+\fIx\fR\u\s-32\s+3\d+\fIx\fR+1
+\fIG\fR(\fIx\fR)=\fIx\fR**32+\fIx\fR**26+\fIx\fR**23+\fIx\fR**22+\fIx\fR**16+\fIx\fR**12+\fIx\fR**11+
+     \fIx\fR**10+\fIx\fR**8+\fIx\fR**7+\fIx\fR**5+\fIx\fR**4+\fIx\fR**2+\fIx\fR+1
 .fi
 .P
 .RE
@@ -58,7 +59,7 @@ capable of representing this integer shall be used.
 .IR M (\c
 .IR x )
 is multiplied by
-.IR x \u\s-332\s+3\d
+.IR x **32
 (that is, shifted left 32 bits) and divided by
 .IR G (\c
 .IR x )
diff --git a/man-pages-posix-2017/man1p/pax.1p b/man-pages-posix-2017/man1p/pax.1p
index cd34bb2..db39781 100644
--- a/man-pages-posix-2017/man1p/pax.1p
+++ b/man-pages-posix-2017/man1p/pax.1p
@@ -3191,7 +3191,7 @@ block value of 10\|240 bytes for
 .IR tar
 was selected because that is the standard block-size value for BSD
 .IR tar .
-The maximum block size of 32\|256 bytes (2\s-3\u15\d\s+3\-512 bytes)
+The maximum block size of 32\|256 bytes (2**15\-512 bytes)
 is the largest multiple of 512 bytes that fits into a signed 16-bit
 tape controller transfer register. There are known limitations in some
 historical systems that would prevent larger blocks from being
diff --git a/man-pages-posix-2017/man3p/cexp.3p b/man-pages-posix-2017/man3p/cexp.3p
index 7d6cd7c..388f449 100644
--- a/man-pages-posix-2017/man3p/cexp.3p
+++ b/man-pages-posix-2017/man3p/cexp.3p
@@ -28,7 +28,7 @@ ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the I
 .P
 These functions shall compute the complex exponent of
 .IR z ,
-defined as \fIe\s-3\uz\d\s+3\fR.
+defined as \fIe**z\fR.
 .SH "RETURN VALUE"
 These functions shall return the complex exponential value of
 .IR z .
diff --git a/man-pages-posix-2017/man3p/cpow.3p b/man-pages-posix-2017/man3p/cpow.3p
index bb53e62..e0d673d 100644
--- a/man-pages-posix-2017/man3p/cpow.3p
+++ b/man-pages-posix-2017/man3p/cpow.3p
@@ -28,7 +28,7 @@ ISO\ C standard. Any conflict between the requirements described here and the
 ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
 .P
 These functions shall compute the complex power function
-\fIx\s-3\uy\d\s+3\fR, with a branch cut for the first parameter along
+\fIx**y\fR, with a branch cut for the first parameter along
 the negative real axis.
 .SH "RETURN VALUE"
 These functions shall return the complex power function value.
diff --git a/man-pages-posix-2017/man3p/drand48.3p b/man-pages-posix-2017/man3p/drand48.3p
index 7157971..29c58a0 100644
--- a/man-pages-posix-2017/man3p/drand48.3p
+++ b/man-pages-posix-2017/man3p/drand48.3p
@@ -52,14 +52,14 @@ The
 and
 \fInrand48\fR()
 functions shall return non-negative, long integers, uniformly
-distributed over the interval [0,2\u\s-331\s+3\d).
+distributed over the interval [0,2**31).
 .P
 The
 \fImrand48\fR()
 and
 \fIjrand48\fR()
 functions shall return signed long integers uniformly distributed over
-the interval [\-2\u\s-331\s+3\d,2\u\s-331\s+3\d).
+the interval [\-2**31,2**31).
 .P
 The
 \fIsrand48\fR(),
diff --git a/man-pages-posix-2017/man3p/exp2.3p b/man-pages-posix-2017/man3p/exp2.3p
index 23cb8bf..c49f455 100644
--- a/man-pages-posix-2017/man3p/exp2.3p
+++ b/man-pages-posix-2017/man3p/exp2.3p
@@ -39,7 +39,7 @@ is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO |
 FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred.
 .SH "RETURN VALUE"
 Upon successful completion, these functions shall return
-2\fI\s-3\ux\d\s+3\fR.
+2\fI**x\fR.
 .P
 If the correct value would cause overflow, a range error shall occur
 and
diff --git a/man-pages-posix-2017/man3p/expm1.3p b/man-pages-posix-2017/man3p/expm1.3p
index 8db897e..5fb15c1 100644
--- a/man-pages-posix-2017/man3p/expm1.3p
+++ b/man-pages-posix-2017/man3p/expm1.3p
@@ -26,7 +26,7 @@ The functionality described on this reference page is aligned with the
 ISO\ C standard. Any conflict between the requirements described here and the
 ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
 .P
-These functions shall compute \fIe\u\s-3x\s+3\d\fR\-1.0.
+These functions shall compute \fIe**x\fR\-1.0.
 .P
 An application wishing to check for error situations should set
 .IR errno
@@ -38,7 +38,7 @@ is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO |
 FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred.
 .SH "RETURN VALUE"
 Upon successful completion, these functions return
-\fIe\s-3\ux\d\s+3\fR\-1.0.
+\fIe**x\fR\-1.0.
 .P
 If the correct value would cause overflow, a range error shall occur
 and
@@ -131,7 +131,7 @@ The
 and
 \fIlog1p\fR()
 functions are useful for financial calculations of
-((1+\fIx\fR)\u\s-3\fIn\fR\s+3\d\-1)/\fIx\fR, namely:
+((1+\fIx\fR)**\fIn\fR\-1)/\fIx\fR, namely:
 .sp
 .RS 4
 .nf
diff --git a/man-pages-posix-2017/man3p/hypot.3p b/man-pages-posix-2017/man3p/hypot.3p
index 095a572..f099eed 100644
--- a/man-pages-posix-2017/man3p/hypot.3p
+++ b/man-pages-posix-2017/man3p/hypot.3p
@@ -27,8 +27,8 @@ ISO\ C standard. Any conflict between the requirements described here and the
 ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
 .P
 These functions shall compute the value of the square root of
-.IR x \s-3\u2\d\s+3+\c
-.IR y \s-3\u2\d\s+3
+.IR x **2+\c
+.IR y **2
 without undue overflow or underflow.
 .P
 An application wishing to check for error situations should set
diff --git a/man-pages-posix-2017/man3p/initstate.3p b/man-pages-posix-2017/man3p/initstate.3p
index dcb3cc0..2683bc5 100644
--- a/man-pages-posix-2017/man3p/initstate.3p
+++ b/man-pages-posix-2017/man3p/initstate.3p
@@ -30,13 +30,13 @@ function shall use a non-linear additive feedback random-number
 generator employing a default state array size of 31
 .BR long
 integers to return successive pseudo-random numbers in the range from 0
-to 2\u\s-331\s+3\d\-1. The period of this random-number generator is
-approximately 16 x (2\s-3\u31\d\s+3\-\fR1). The size of the state
+to 2**31\-1. The period of this random-number generator is
+approximately 16 x (2**31\-\fR1). The size of the state
 array determines the period of the random-number generator. Increasing
 the state array size shall increase the period.
 .P
 With 256 bytes of state information, the period of the random-number
-generator shall be greater than 2\s-3\u69\d\s+3.
+generator shall be greater than 2**69.
 .P
 Like
 \fIrand\fR(),
diff --git a/man-pages-posix-2017/man3p/ldexp.3p b/man-pages-posix-2017/man3p/ldexp.3p
index 86196d9..63b718a 100644
--- a/man-pages-posix-2017/man3p/ldexp.3p
+++ b/man-pages-posix-2017/man3p/ldexp.3p
@@ -27,7 +27,7 @@ ISO\ C standard. Any conflict between the requirements described here and the
 ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
 .P
 These functions shall compute the quantity
-\fIx\fR\ *\ 2\u\s-3\fIexp\fR\s+3\d.
+\fIx\fR\ *\ 2**\fIexp\fR.
 .P
 An application wishing to check for error situations should set
 .IR errno
diff --git a/man-pages-posix-2017/man3p/logb.3p b/man-pages-posix-2017/man3p/logb.3p
index 1f1b4de..09bb1c6 100644
--- a/man-pages-posix-2017/man3p/logb.3p
+++ b/man-pages-posix-2017/man3p/logb.3p
@@ -47,7 +47,7 @@ finite positive
 .RS 4
 .nf
 
-1 <= \fIx\fP * FLT_RADIX\s-3\u-logb(x)\d\s+3 < FLT_RADIX
+1 <= \fIx\fP * FLT_RADIX**(-logb(x)) < FLT_RADIX
 .fi
 .P
 .RE
diff --git a/man-pages-posix-2017/man3p/pow.3p b/man-pages-posix-2017/man3p/pow.3p
index 1e28125..4cbee11 100644
--- a/man-pages-posix-2017/man3p/pow.3p
+++ b/man-pages-posix-2017/man3p/pow.3p
@@ -30,7 +30,7 @@ These functions shall compute the value of
 .IR x
 raised to the power
 .IR y ,
-.IR x\u\s-3y\s+3\d .
+.IR x**y .
 If
 .IR x
 is negative, the application shall ensure that
diff --git a/man-pages-posix-2017/man3p/rand.3p b/man-pages-posix-2017/man3p/rand.3p
index 63c9cdf..889bac0 100644
--- a/man-pages-posix-2017/man3p/rand.3p
+++ b/man-pages-posix-2017/man3p/rand.3p
@@ -35,7 +35,7 @@ The
 function shall compute a sequence of pseudo-random integers in the
 range [0,\c
 {RAND_MAX}]
-with a period of at least 2\u\s-332\s0\d.
+with a period of at least 2**32
 .P
 The
 \fIrand\fR()
diff --git a/man-pages-posix-2017/man3p/remquo.3p b/man-pages-posix-2017/man3p/remquo.3p
index 1a609f1..00f4f23 100644
--- a/man-pages-posix-2017/man3p/remquo.3p
+++ b/man-pages-posix-2017/man3p/remquo.3p
@@ -41,7 +41,7 @@ functions, respectively. In the object pointed to by
 they store a value whose sign is the sign of
 .IR x /\c
 .IR y
-and whose magnitude is congruent modulo 2\fI\s-3\un\d\s+3\fR to the
+and whose magnitude is congruent modulo 2\fI**n\fR to the
 magnitude of the integral quotient of
 .IR x /\c
 .IR y ,
diff --git a/man-pages-posix-2017/man3p/scalbln.3p b/man-pages-posix-2017/man3p/scalbln.3p
index 788ce42..13fa729 100644
--- a/man-pages-posix-2017/man3p/scalbln.3p
+++ b/man-pages-posix-2017/man3p/scalbln.3p
@@ -32,8 +32,8 @@ The functionality described on this reference page is aligned with the
 ISO\ C standard. Any conflict between the requirements described here and the
 ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
 .P
-These functions shall compute \fIx\fR\ *\ FLT_RADIX\fI\s-3\un\d\s+3\fR
-efficiently, not normally by computing FLT_RADIX\fI\s-3\un\d\s+3\fR
+These functions shall compute \fIx\fR\ *\ FLT_RADIX**\fIn\fR
+efficiently, not normally by computing FLT_RADIX**\fIn\fR
 explicitly.
 .P
 An application wishing to check for error situations should set
@@ -46,7 +46,7 @@ is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO |
 FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred.
 .SH "RETURN VALUE"
 Upon successful completion, these functions shall return
-\fIx\fR\ *\ FLT_RADIX\fI\s-3\un\d\s+3\fR.
+\fIx\fR\ *\ FLT_RADIX**\fIn\fR.
 .P
 If the result would cause overflow, a range error shall occur and these
 functions shall return \(+-HUGE_VAL, \(+-HUGE_VALF, and \(+-HUGE_VALL



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/