Re: master ac1d15e95c 1/2: ; * src/data.c (Fash): More precise doc string

Re: master ac1d15e95c 1/2: ; * src/data.c (Fash): More precise doc string

[Eli Zaretskii]

> branch: master
> commit ac1d15e95c88592325afebb3d82c8c74a27d2627
> Author: Mattias Engdegård <mattiase@acm.org>
> Commit: Mattias Engdegård <mattiase@acm.org>
> 
>     ; * src/data.c (Fash): More precise doc string
> ---
>  src/data.c | 4 +++-
>  1 file changed, 3 insertions(+), 1 deletion(-)
> 
> diff --git a/src/data.c b/src/data.c
> index 568349ba83..b2fcdaebee 100644
> --- a/src/data.c
> +++ b/src/data.c
> @@ -3519,7 +3519,9 @@ representation.  */)
>  DEFUN ("ash", Fash, Sash, 2, 2, 0,
>         doc: /* Return VALUE with its bits shifted left by COUNT.
>  If COUNT is negative, shifting is actually to the right.
> -In this case, the sign bit is duplicated.  */)
> +The return value is always VALUE multiplied by 2 to the power of COUNT,
> +rounding down (towards negative infinity).
> +VALUE and COUNT must be integers.  */)
>    (Lisp_Object value, Lisp_Object count)

I'm afraid I find the modified doc string less self-explanatory wrt
what happens when VALUE is negative.  It might be more accurate, but
makes it harder to understand what happens in that case.

Can we do better here, please?

Thanks.

Re: master ac1d15e95c 1/2: ; * src/data.c (Fash): More precise doc string

[Mattias Engdegård]

19 juli 2022 kl. 15.49 skrev Eli Zaretskii <eliz@gnu.org>:

> I'm afraid I find the modified doc string less self-explanatory wrt
> what happens when VALUE is negative.  It might be more accurate, but
> makes it harder to understand what happens in that case.

The old text was definitely not self-explanatory; it made me more confused than enlightened.
But let's try again. What about:

Return VALUE with its bits shifted left by COUNT.
If COUNT is negative, shifting is actually to the right.
Values are shifted as an infinitely wide two's complement representation; each shift step multiplies (left-shifting) or divides (right-shifting) the value by two, rounding down.
VALUE and COUNT must be integers.

Re: master ac1d15e95c 1/2: ; * src/data.c (Fash): More precise doc string

[Eli Zaretskii]

> From: Mattias Engdegård <mattiase@acm.org>
> Date: Tue, 19 Jul 2022 16:19:52 +0200
> Cc: emacs-devel@gnu.org
> 
> 19 juli 2022 kl. 15.49 skrev Eli Zaretskii <eliz@gnu.org>:
> 
> > I'm afraid I find the modified doc string less self-explanatory wrt
> > what happens when VALUE is negative.  It might be more accurate, but
> > makes it harder to understand what happens in that case.
> 
> The old text was definitely not self-explanatory; it made me more confused than enlightened.
> But let's try again. What about:
> 
> Return VALUE with its bits shifted left by COUNT.
> If COUNT is negative, shifting is actually to the right.
> Values are shifted as an infinitely wide two's complement representation; each shift step multiplies (left-shifting) or divides (right-shifting) the value by two, rounding down.
> VALUE and COUNT must be integers.

IMO, that's too technical, and thus too demanding on the reader:

  . it requires the reader to know about two's complement representation
  . it requires the reader to imagine "infinitely-wide" binary values
  . it requires the reader to understand that shifting, multiplication,
    and division are equivalent
  . it requires the reader to understand the notion of "rounding down"

How about explaining in simple words what this does to positive and
negative values shifted left and right?

One possible way to explain that is what the ELisp manual does.  But
it isn't the only one.

Re: master ac1d15e95c 1/2: ; * src/data.c (Fash): More precise doc string

[Mattias Engdegård]

19 juli 2022 kl. 16.26 skrev Eli Zaretskii <eliz@gnu.org>:

>  . it requires the reader to understand that shifting, multiplication,
>    and division are equivalent
>  . it requires the reader to understand the notion of "rounding down"

You certainly don't think highly of elisp programmers...

> How about explaining in simple words what this does to positive and
> negative values shifted left and right?
> 
> One possible way to explain that is what the ELisp manual does.

The manual uses the same definition as the doc string now uses.
But let's try once more:

Shifting left one step multiplies the value by two.
Shifting right one step divides the value by two, after first decrementing the value by one if it was odd.

Re: master ac1d15e95c 1/2: ; * src/data.c (Fash): More precise doc string

[Eli Zaretskii]

> From: Mattias Engdegård <mattiase@acm.org>
> Date: Tue, 19 Jul 2022 17:08:48 +0200
> Cc: emacs-devel@gnu.org
> 
> 19 juli 2022 kl. 16.26 skrev Eli Zaretskii <eliz@gnu.org>:
> 
> >  . it requires the reader to understand that shifting, multiplication,
> >    and division are equivalent
> >  . it requires the reader to understand the notion of "rounding down"
> 
> You certainly don't think highly of elisp programmers...

That's besides the point.  Clear documentation should be
understandable by everyone.

> Shifting left one step multiplies the value by two.
> Shifting right one step divides the value by two, after first decrementing the value by one if it was odd.

Still not there, sorry.

It is okay to say that shifting is the same as multiplying or
dividing, but why say _only_ that?  The operation is "bit shift", so
the most natural way of describing it is in terms of shifting bits.
No?

Re: master ac1d15e95c 1/2: ; * src/data.c (Fash): More precise doc string

[Stefan Monnier]

> Return VALUE with its bits shifted left by COUNT.
> If COUNT is negative, shifting is actually to the right.
> Values are shifted as an infinitely wide two's complement representation;
> each shift step multiplies (left-shifting) or divides (right-shifting) the
> value by two, rounding down.
> VALUE and COUNT must be integers.

I like the "2 to the power N" part of the new doc, so I'd encourage
keeping it.


        Stefan

Re: master ac1d15e95c 1/2: ; * src/data.c (Fash): More precise doc string

[Mattias Engdegård]

19 juli 2022 kl. 17.54 skrev Eli Zaretskii <eliz@gnu.org>:

> The operation is "bit shift", so
> the most natural way of describing it is in terms of shifting bits.
> No?

Not necessarily. The user inputs numbers and gets a number out, not bit sequences, so it makes sense to describe the behaviour in arithmetic terms. (We're not describing a processor instruction that manipulates registers; `ash` is an operation on mathematical integers.)

A bitwise description would require knowledge of two's complement representation which you dismissed earlier. If it's acceptable to complement the arithmetic description with something that refers to such representation, then we could have:

  If we view VALUE as a binary two's complement number, then shifting left introduce new 0-bits to the right and shifting right remove rightmost bits.
  Since negative numbers have an infinite supply of 1-bits to the left, a negative number remains negative no matter how far it is shifted in either direction.

Re: master ac1d15e95c 1/2: ; * src/data.c (Fash): More precise doc string

[Eli Zaretskii]

> From: Mattias Engdegård <mattiase@acm.org>
> Date: Tue, 19 Jul 2022 19:46:24 +0200
> Cc: emacs-devel@gnu.org
> 
> 19 juli 2022 kl. 17.54 skrev Eli Zaretskii <eliz@gnu.org>:
> 
> > The operation is "bit shift", so
> > the most natural way of describing it is in terms of shifting bits.
> > No?
> 
> Not necessarily. The user inputs numbers and gets a number out, not bit sequences, so it makes sense to describe the behaviour in arithmetic terms. (We're not describing a processor instruction that manipulates registers; `ash` is an operation on mathematical integers.)
> 
> A bitwise description would require knowledge of two's complement representation which you dismissed earlier. If it's acceptable to complement the arithmetic description with something that refers to such representation, then we could have:
> 
>   If we view VALUE as a binary two's complement number, then shifting left introduce new 0-bits to the right and shifting right remove rightmost bits.
>   Since negative numbers have an infinite supply of 1-bits to the left, a negative number remains negative no matter how far it is shifted in either direction.

Sigh.  You know what, forget about this.  I will fix this myself, time
permitting.

Re: master ac1d15e95c 1/2: ; * src/data.c (Fash): More precise doc string

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > It is okay to say that shifting is the same as multiplying or
  > dividing, but why say _only_ that?  The operation is "bit shift", so
  > the most natural way of describing it is in terms of shifting bits.

That's the way I think of it.

However, when you're not dealing with a fixed width, and negative
numbers are included, it may be necessary to specify precisely the
behavior of right-shift on negative numbers.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)