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

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

Hi Alex,

On 2/14/21 1:23 PM, Alejandro Colomar (man-pages) wrote:
> Hi Michael,
> 
> On 2/14/21 12:34 PM, Michael Kerrisk (man-pages) wrote:
>> 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.
> 
> I guess this is caused by posix.py, right?  If so, would you mind
> patching that so that future POSIX revisions are also fixed?
> I don't understand that file so much...

Unfortunately, it's not quite so simple. There was at least one
case (od.1p) where this fix was not correct (i.e., superscripting
was not being used to mean power-of). Plus there was at least one
case where a long line needed to be manually wrapped (cksum.1p).
Plus, sometimes the \u..\d was used in conjunction
with font-size change markup (\s-N...\s+N) that was variously
inside or outside the \u...\d. Plus, sometimes parentheses needed
to be added around the superscript value. All of it is probably
solvable with some (slightly complicated) scripting, but for now
the manual edit just seemed much faster.

>> 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?
> 
> I didn't read all of them, but from the first few, looks good to me.
Thanks for taking a look.

Cheers,

Michael

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