Re: exp.3: remove ancient history and some markup tweaks

[Ingo Schwarze]

Hi Theo,

Theo Buehler wrote on Mon, May 30, 2016 at 07:33:04PM +0200:

> Fine. Here's the diff only doing the markup stuff.

No objection here if you think it reads better.  The spacing is a
matter of personal taste.  I'm not aware of any recommendation
whether to insert spacing into in-line mathematical formulae in
mdoc(7) code.

GNU eqn(1) removes the spacing even if you provide it:

  schwarze@isnote $ eqn -Tascii | nroff -mdoc -Tascii -c -p | hexdump -C
  .EQ
  x + 1
  .EN
    5f 08 78 2b 31 0a ...  |_.x+1.|

But that's not a strong argument.
Besides, mandoc(1) currently does not:

  schwarze@isnote $ mandoc | hexdump -C
  .EQ
  x + 1
  .EN
  [...]
  0050  0a 0a 78 20 2b 20 31 0a ...  |..x + 1.|

In mathematical formulae, \(mi is slightly better than \- for minus.

Yours,
  Ingo


> Index: exp.3
> ===
> RCS file: /var/cvs/src/lib/libm/man/exp.3,v
> retrieving revision 1.33
> diff -u -p -r1.33 exp.3
> --- exp.3 26 Apr 2016 19:49:22 -  1.33
> +++ exp.3 30 May 2016 17:30:40 -
> @@ -139,7 +139,7 @@ function is an extended precision versio
>  .Pp
>  The
>  .Fn expm1
> -function computes the value exp(x)\-1 accurately even for tiny argument
> +function computes the value exp(x) \(mi 1 accurately even for tiny argument
>  .Fa x .
>  The
>  .Fn expm1f
> @@ -194,7 +194,7 @@ function is an extended precision versio
>  The
>  .Fn log1p
>  function computes
> -the value of log(1+x) accurately even for tiny argument
> +the value of log(1 + x) accurately even for tiny argument
>  .Fa x .
>  The
>  .Fn log1pf
> @@ -277,12 +277,12 @@ are accurate enough that
>  .Fn pow integer integer
>  is exact until it is bigger than 2**53 for IEEE 754.
>  .Sh NOTES
> -The functions exp(x)\-1 and log(1+x) are called
> +The functions exp(x) \(mi 1 and log(1 + x) are called
>  expm1 and logp1 in BASIC on the Hewlett\-Packard HP-71B
>  and APPLE Macintosh, EXP1 and LN1 in Pascal, exp1 and log1 in C
>  on APPLE Macintoshes, where they have been provided to make
> -sure financial calculations of ((1+x)**n\-1)/x, namely
> -expm1(n*log1p(x))/x, will be accurate when x is tiny.
> +sure financial calculations of ((1 + x)**n \(mi 1) / x, namely
> +expm1(n * log1p(x)) / x, will be accurate when x is tiny.
>  They also provide accurate inverse hyperbolic functions.
>  .Pp
>  The function

Re: exp.3: remove ancient history and some markup tweaks

[Mark Kettenis]

> Date: Mon, 30 May 2016 19:33:04 +0200
> From: Theo Buehler 
> 
> > Sorry.  No.  The use of originally still implies that these functions
> > are no longer relevant for the purpose mentioned in the sentence.  It
> > doesn't make sense without the historic context.  I'd simply leave the
> > NOTES section as-is.
> 
> Fine. Here's the diff only doing the markup stuff.

Not an mdoc expert, but this looks good to me.

> Index: exp.3
> ===
> RCS file: /var/cvs/src/lib/libm/man/exp.3,v
> retrieving revision 1.33
> diff -u -p -r1.33 exp.3
> --- exp.3 26 Apr 2016 19:49:22 -  1.33
> +++ exp.3 30 May 2016 17:30:40 -
> @@ -139,7 +139,7 @@ function is an extended precision versio
>  .Pp
>  The
>  .Fn expm1
> -function computes the value exp(x)\-1 accurately even for tiny argument
> +function computes the value exp(x) \(mi 1 accurately even for tiny argument
>  .Fa x .
>  The
>  .Fn expm1f
> @@ -194,7 +194,7 @@ function is an extended precision versio
>  The
>  .Fn log1p
>  function computes
> -the value of log(1+x) accurately even for tiny argument
> +the value of log(1 + x) accurately even for tiny argument
>  .Fa x .
>  The
>  .Fn log1pf
> @@ -277,12 +277,12 @@ are accurate enough that
>  .Fn pow integer integer
>  is exact until it is bigger than 2**53 for IEEE 754.
>  .Sh NOTES
> -The functions exp(x)\-1 and log(1+x) are called
> +The functions exp(x) \(mi 1 and log(1 + x) are called
>  expm1 and logp1 in BASIC on the Hewlett\-Packard HP-71B
>  and APPLE Macintosh, EXP1 and LN1 in Pascal, exp1 and log1 in C
>  on APPLE Macintoshes, where they have been provided to make
> -sure financial calculations of ((1+x)**n\-1)/x, namely
> -expm1(n*log1p(x))/x, will be accurate when x is tiny.
> +sure financial calculations of ((1 + x)**n \(mi 1) / x, namely
> +expm1(n * log1p(x)) / x, will be accurate when x is tiny.
>  They also provide accurate inverse hyperbolic functions.
>  .Pp
>  The function
> 

Re: exp.3: remove ancient history and some markup tweaks

[Mark Kettenis]

> Date: Mon, 30 May 2016 18:55:42 +0200
> From: Theo Buehler 
> 
> On Mon, May 30, 2016 at 06:24:55PM +0200, Mark Kettenis wrote:
> > > Date: Mon, 30 May 2016 15:34:04 +0200
> > > From: Joerg Sonnenberger 
> > > 
> > > On Mon, May 30, 2016 at 02:16:20PM +0200, Theo Buehler wrote:
> > > > It may be somewhat interesting to mention why expm1(x) = exp(x) - 1 and
> > > > log1p(x) = log(1 + x) are provided and what their historical purpose is.
> > > > However, as mlarkin@ put it: are any of our users of exp(3) going to
> > > > seriously be asking themselves "hmm, is OpenBSD's exp compatible with
> > > > BASIC on the HP-71B?"
> > > 
> > > The wording change also changes the semantics quite a bit. The old
> > > wording explained where the name came from and what the function does.
> > > The new wording implies somewhat that the functions are obsolete, which
> > > is far from true.
> > 
> > Right.  The function is as releveant as ever. And not only for
> > "financial" calculations.  The new text isn't an improvment.
> 
> Ok, maybe the choice of the word 'historically' was suboptimal.  I
> didn't intend to imply irrelevance or obsolescence.  Note also that this
> is in the NOTES section, not in the DESCRIPTION section.
> 
> How about this?

Sorry.  No.  The use of originally still implies that these functions
are no longer relevant for the purpose mentioned in the sentence.  It
doesn't make sense without the historic context.  I'd simply leave the
NOTES section as-is.

> Index: exp.3
> ===
> RCS file: /var/cvs/src/lib/libm/man/exp.3,v
> retrieving revision 1.33
> diff -u -p -r1.33 exp.3
> --- exp.3 26 Apr 2016 19:49:22 -  1.33
> +++ exp.3 30 May 2016 16:38:34 -
> @@ -139,7 +139,7 @@ function is an extended precision versio
>  .Pp
>  The
>  .Fn expm1
> -function computes the value exp(x)\-1 accurately even for tiny argument
> +function computes the value exp(x) \(mi 1 accurately even for tiny argument
>  .Fa x .
>  The
>  .Fn expm1f
> @@ -194,7 +194,7 @@ function is an extended precision versio
>  The
>  .Fn log1p
>  function computes
> -the value of log(1+x) accurately even for tiny argument
> +the value of log(1 + x) accurately even for tiny argument
>  .Fa x .
>  The
>  .Fn log1pf
> @@ -277,12 +277,9 @@ are accurate enough that
>  .Fn pow integer integer
>  is exact until it is bigger than 2**53 for IEEE 754.
>  .Sh NOTES
> -The functions exp(x)\-1 and log(1+x) are called
> -expm1 and logp1 in BASIC on the Hewlett\-Packard HP-71B
> -and APPLE Macintosh, EXP1 and LN1 in Pascal, exp1 and log1 in C
> -on APPLE Macintoshes, where they have been provided to make
> -sure financial calculations of ((1+x)**n\-1)/x, namely
> -expm1(n*log1p(x))/x, will be accurate when x is tiny.
> +Originally, expm1(x) = exp(x) \(mi 1 and log1p(x) = log(1 + x)
> +were used to ensure financial calculations of ((1 + x)**n \(mi 1) / x,
> +namely expm1(n * log1p(x)) / x, are accurate when x is tiny.
>  They also provide accurate inverse hyperbolic functions.
>  .Pp
>  The function
> 
> 
> 

Re: exp.3: remove ancient history and some markup tweaks

[Theo Buehler]

> Sorry.  No.  The use of originally still implies that these functions
> are no longer relevant for the purpose mentioned in the sentence.  It
> doesn't make sense without the historic context.  I'd simply leave the
> NOTES section as-is.

Fine. Here's the diff only doing the markup stuff.

Index: exp.3
===
RCS file: /var/cvs/src/lib/libm/man/exp.3,v
retrieving revision 1.33
diff -u -p -r1.33 exp.3
--- exp.3   26 Apr 2016 19:49:22 -  1.33
+++ exp.3   30 May 2016 17:30:40 -
@@ -139,7 +139,7 @@ function is an extended precision versio
 .Pp
 The
 .Fn expm1
-function computes the value exp(x)\-1 accurately even for tiny argument
+function computes the value exp(x) \(mi 1 accurately even for tiny argument
 .Fa x .
 The
 .Fn expm1f
@@ -194,7 +194,7 @@ function is an extended precision versio
 The
 .Fn log1p
 function computes
-the value of log(1+x) accurately even for tiny argument
+the value of log(1 + x) accurately even for tiny argument
 .Fa x .
 The
 .Fn log1pf
@@ -277,12 +277,12 @@ are accurate enough that
 .Fn pow integer integer
 is exact until it is bigger than 2**53 for IEEE 754.
 .Sh NOTES
-The functions exp(x)\-1 and log(1+x) are called
+The functions exp(x) \(mi 1 and log(1 + x) are called
 expm1 and logp1 in BASIC on the Hewlett\-Packard HP-71B
 and APPLE Macintosh, EXP1 and LN1 in Pascal, exp1 and log1 in C
 on APPLE Macintoshes, where they have been provided to make
-sure financial calculations of ((1+x)**n\-1)/x, namely
-expm1(n*log1p(x))/x, will be accurate when x is tiny.
+sure financial calculations of ((1 + x)**n \(mi 1) / x, namely
+expm1(n * log1p(x)) / x, will be accurate when x is tiny.
 They also provide accurate inverse hyperbolic functions.
 .Pp
 The function

Re: exp.3: remove ancient history and some markup tweaks

[Theo Buehler]

On Mon, May 30, 2016 at 06:24:55PM +0200, Mark Kettenis wrote:
> > Date: Mon, 30 May 2016 15:34:04 +0200
> > From: Joerg Sonnenberger 
> > 
> > On Mon, May 30, 2016 at 02:16:20PM +0200, Theo Buehler wrote:
> > > It may be somewhat interesting to mention why expm1(x) = exp(x) - 1 and
> > > log1p(x) = log(1 + x) are provided and what their historical purpose is.
> > > However, as mlarkin@ put it: are any of our users of exp(3) going to
> > > seriously be asking themselves "hmm, is OpenBSD's exp compatible with
> > > BASIC on the HP-71B?"
> > 
> > The wording change also changes the semantics quite a bit. The old
> > wording explained where the name came from and what the function does.
> > The new wording implies somewhat that the functions are obsolete, which
> > is far from true.
> 
> Right.  The function is as releveant as ever. And not only for
> "financial" calculations.  The new text isn't an improvment.

Ok, maybe the choice of the word 'historically' was suboptimal.  I
didn't intend to imply irrelevance or obsolescence.  Note also that this
is in the NOTES section, not in the DESCRIPTION section.

How about this?

Index: exp.3
===
RCS file: /var/cvs/src/lib/libm/man/exp.3,v
retrieving revision 1.33
diff -u -p -r1.33 exp.3
--- exp.3   26 Apr 2016 19:49:22 -  1.33
+++ exp.3   30 May 2016 16:38:34 -
@@ -139,7 +139,7 @@ function is an extended precision versio
 .Pp
 The
 .Fn expm1
-function computes the value exp(x)\-1 accurately even for tiny argument
+function computes the value exp(x) \(mi 1 accurately even for tiny argument
 .Fa x .
 The
 .Fn expm1f
@@ -194,7 +194,7 @@ function is an extended precision versio
 The
 .Fn log1p
 function computes
-the value of log(1+x) accurately even for tiny argument
+the value of log(1 + x) accurately even for tiny argument
 .Fa x .
 The
 .Fn log1pf
@@ -277,12 +277,9 @@ are accurate enough that
 .Fn pow integer integer
 is exact until it is bigger than 2**53 for IEEE 754.
 .Sh NOTES
-The functions exp(x)\-1 and log(1+x) are called
-expm1 and logp1 in BASIC on the Hewlett\-Packard HP-71B
-and APPLE Macintosh, EXP1 and LN1 in Pascal, exp1 and log1 in C
-on APPLE Macintoshes, where they have been provided to make
-sure financial calculations of ((1+x)**n\-1)/x, namely
-expm1(n*log1p(x))/x, will be accurate when x is tiny.
+Originally, expm1(x) = exp(x) \(mi 1 and log1p(x) = log(1 + x)
+were used to ensure financial calculations of ((1 + x)**n \(mi 1) / x,
+namely expm1(n * log1p(x)) / x, are accurate when x is tiny.
 They also provide accurate inverse hyperbolic functions.
 .Pp
 The function

Re: exp.3: remove ancient history and some markup tweaks

[Mark Kettenis]

> Date: Mon, 30 May 2016 15:34:04 +0200
> From: Joerg Sonnenberger 
> 
> On Mon, May 30, 2016 at 02:16:20PM +0200, Theo Buehler wrote:
> > It may be somewhat interesting to mention why expm1(x) = exp(x) - 1 and
> > log1p(x) = log(1 + x) are provided and what their historical purpose is.
> > However, as mlarkin@ put it: are any of our users of exp(3) going to
> > seriously be asking themselves "hmm, is OpenBSD's exp compatible with
> > BASIC on the HP-71B?"
> 
> The wording change also changes the semantics quite a bit. The old
> wording explained where the name came from and what the function does.
> The new wording implies somewhat that the functions are obsolete, which
> is far from true.

Right.  The function is as releveant as ever. And not only for
"financial" calculations.  The new text isn't an improvment.

Re: exp.3: remove ancient history and some markup tweaks

[Joerg Sonnenberger]

On Mon, May 30, 2016 at 04:30:10PM +0200, Marc Espie wrote:
> On Mon, May 30, 2016 at 03:34:04PM +0200, Joerg Sonnenberger wrote:
> > On Mon, May 30, 2016 at 02:16:20PM +0200, Theo Buehler wrote:
> > > It may be somewhat interesting to mention why expm1(x) = exp(x) - 1 and
> > > log1p(x) = log(1 + x) are provided and what their historical purpose is.
> > > However, as mlarkin@ put it: are any of our users of exp(3) going to
> > > seriously be asking themselves "hmm, is OpenBSD's exp compatible with
> > > BASIC on the HP-71B?"
> > 
> > The wording change also changes the semantics quite a bit. The old
> > wording explained where the name came from and what the function does.
> > The new wording implies somewhat that the functions are obsolete, which
> > is far from true.
> 
> Huh ?
> "computes the value ... accurately even for tiny arguments".
> 
> That's quite enough as far as a function description goes.

Look at the changed NOTES section. The rest is fine.

Joerg

Re: exp.3: remove ancient history and some markup tweaks

[Marc Espie]

On Mon, May 30, 2016 at 03:34:04PM +0200, Joerg Sonnenberger wrote:
> On Mon, May 30, 2016 at 02:16:20PM +0200, Theo Buehler wrote:
> > It may be somewhat interesting to mention why expm1(x) = exp(x) - 1 and
> > log1p(x) = log(1 + x) are provided and what their historical purpose is.
> > However, as mlarkin@ put it: are any of our users of exp(3) going to
> > seriously be asking themselves "hmm, is OpenBSD's exp compatible with
> > BASIC on the HP-71B?"
> 
> The wording change also changes the semantics quite a bit. The old
> wording explained where the name came from and what the function does.
> The new wording implies somewhat that the functions are obsolete, which
> is far from true.

Huh ?
"computes the value ... accurately even for tiny arguments".

That's quite enough as far as a function description goes.


When it does matter, you're pretty much going to lose anyway.
You can possibly want to add references to external texts
(Art of computer programming, Numerical recipes, or any decent IEEE754
text would do... 

https://people.eecs.berkeley.edu/~wkahan/ieee754status/IEEE754.PDF
is probably the best short reference IMO), but if people do floating point
stuff without understanding the basics, the manpage isn't really going to
help anyway.


Losing the full historical explanation of the name is not that big a problem;
the names are very much self-explanatory.

Re: exp.3: remove ancient history and some markup tweaks

[Joerg Sonnenberger]

On Mon, May 30, 2016 at 02:16:20PM +0200, Theo Buehler wrote:
> It may be somewhat interesting to mention why expm1(x) = exp(x) - 1 and
> log1p(x) = log(1 + x) are provided and what their historical purpose is.
> However, as mlarkin@ put it: are any of our users of exp(3) going to
> seriously be asking themselves "hmm, is OpenBSD's exp compatible with
> BASIC on the HP-71B?"

The wording change also changes the semantics quite a bit. The old
wording explained where the name came from and what the function does.
The new wording implies somewhat that the functions are obsolete, which
is far from true.

Joerg