Re: [PATCH] nextup.3: minor improvements

[Vincent Lefevre <vincent@vinc17.net>]

On 2024-08-07 23:19:56 +0200, Alejandro Colomar wrote:
> Hi Vincent,
> 
> On Wed, Aug 07, 2024 at 12:56:17PM GMT, Vincent Lefevre wrote:
> > The current "If x is 0" is a bit misleading because "is" is not the
> > equality test, while this condition should apply to both -0 and 0.
> > Replace this condition by "If x is equal to 0".
> 
> How does 'is' differ semantically from 'is equal to' in this case?

"is" designates the value (it is a short for "has the value").
For instance, in the same man page (with the typo fixed):
"If x is NaN" (saying "is equal to" would be incorrect, because
the equality comparison with NaN is always false).

That's why the sqrt(3) man page has

  If x is +0 (-0), +0 (-0) is returned.

and the cbrt(3) man page has

  If x is +0, -0, positive infinity, [...]

"is equal to" corresponds to the usual equality, as written in
a source code. (IEEE 754-2019 actually uses "equals".)

For zero, one can also say "If x is ±0" as in the IEEE 754 standard.
The IEEE 754 standard also uses "zero" in the sense "±0" (but it
never uses "0" in this sense when there may be an ambiguity, knowing
that in practice, "0" has the same meaning as "+0"). In a condition,
when it says something like "x = 0", this means that x is either +0
or -0 because these values compare equal to each other.

So one could also say "If x is zero".

> I don't think 'is equal to' does anything different to mean also -0.

Note that the glibc manual in info format says for nextup:

  If X = ‘0’ the function returns the smallest positive subnormal
  number in the type of X.

and for nextdown:

  If X = ‘0’ the function returns the smallest negative subnormal
  number in the type of X.

> >  If
> >  .I x
> > -is 0, the returned value is the smallest representable positive number
> > -of the corresponding type.
> > +is equal to 0, the returned value is the smallest representable positive
> > +number of the corresponding type.
> 
> Please keep semantic newlines.  See man-pages(7).

I suppose that the issue is here "long clauses should be split at
phrase boundaries", so that you would like to avoid a split between
"positive" and "number". Perhaps better between "is" and "the".

BTW, it seems that this is often not honored, including in new text
(see e.g. commit c86bb39a117fb593f1ff7b7e729d70166d942446 two months
ago, with a split between "undefined" and "behavior").

And should I introduce a newline after the comma, though it is
currently not present? But this will not eliminate the need for
another line break.

-- 
Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / AriC project (LIP, ENS-Lyon)