lsh function documentation

lsh function documentation

[Ulrich Mueller]

The function documentation of lsh says:
| Most uses of this function turn out to be mistakes.  We recommend
| to use ‘ash’ instead, unless COUNT could ever be negative, and
| if, when COUNT is negative, your program really needs the special
| treatment of negative COUNT provided by this function.

I understand that lsh has no useful semantics for negative bignums
(bug #32463). However, old versions of the Lisp Reference Manual list
lsh and ash in the same section, and don't prefer either function:
https://git.savannah.gnu.org/cgit/emacs.git/tree/doc/lispref/numbers.texi?h=emacs-26.3#n811

So why would programmers who had used something like (lsh x 8) in their
code be called out for making a mistake?

Couldn't lsh's documentation just say that the function is deprecated
and that ash should be used instead? 

Re: lsh function documentation

[Eli Zaretskii]

> From: Ulrich Mueller <ulm@gentoo.org>
> Date: Tue, 30 Jan 2024 12:34:59 +0100
> 
> The function documentation of lsh says:
> | Most uses of this function turn out to be mistakes.  We recommend
> | to use ‘ash’ instead, unless COUNT could ever be negative, and
> | if, when COUNT is negative, your program really needs the special
> | treatment of negative COUNT provided by this function.
> 
> I understand that lsh has no useful semantics for negative bignums
> (bug #32463). However, old versions of the Lisp Reference Manual list
> lsh and ash in the same section, and don't prefer either function:
> https://git.savannah.gnu.org/cgit/emacs.git/tree/doc/lispref/numbers.texi?h=emacs-26.3#n811
> 
> So why would programmers who had used something like (lsh x 8) in their
> code be called out for making a mistake?
> 
> Couldn't lsh's documentation just say that the function is deprecated
> and that ash should be used instead? 

We've been there, see bug#56641.

I'm not sure I understand the problem you have with the current text
in the manual and/or the doc string of lsh.

Re: lsh function documentation

[Ulrich Mueller]

>>>>> On Wed, 31 Jan 2024, Eli Zaretskii wrote:

>> From: Ulrich Mueller <ulm@gentoo.org>
>> Date: Tue, 30 Jan 2024 12:34:59 +0100
>> 
>> The function documentation of lsh says:
>> | Most uses of this function turn out to be mistakes.  We recommend
>> | to use ‘ash’ instead, unless COUNT could ever be negative, and
>> | if, when COUNT is negative, your program really needs the special
>> | treatment of negative COUNT provided by this function.
>> 
>> I understand that lsh has no useful semantics for negative bignums
>> (bug #32463). However, old versions of the Lisp Reference Manual list
>> lsh and ash in the same section, and don't prefer either function:
>> https://git.savannah.gnu.org/cgit/emacs.git/tree/doc/lispref/numbers.texi?h=emacs-26.3#n811
>> 
>> So why would programmers who had used something like (lsh x 8) in their
>> code be called out for making a mistake?
>> 
>> Couldn't lsh's documentation just say that the function is deprecated
>> and that ash should be used instead? 

> We've been there, see bug#56641.

> I'm not sure I understand the problem you have with the current text
> in the manual and/or the doc string of lsh.

It's not clear to me what the message "most uses turn out to be
mistakes" tries to communicate. Was it a mistake to use lsh in code
written in the pre-bignum era?

Also, it's not consistent that the function emits a compiler warning,
but at the same time isn't labelled as deprecated. If there are still
valid uses, then there shouldn't be a warning. If not, it should be
deprecated. The current status doesn't make sense IMHO.

Ulrich

Re: lsh function documentation

[Eli Zaretskii]

> From: Ulrich Mueller <ulm@gentoo.org>
> Cc: emacs-devel@gnu.org
> Date: Wed, 31 Jan 2024 17:15:24 +0100
> 
> >>>>> On Wed, 31 Jan 2024, Eli Zaretskii wrote:
> 
> > We've been there, see bug#56641.
> 
> > I'm not sure I understand the problem you have with the current text
> > in the manual and/or the doc string of lsh.
> 
> It's not clear to me what the message "most uses turn out to be
> mistakes" tries to communicate. Was it a mistake to use lsh in code
> written in the pre-bignum era?

Most uses of it, yes.  They should have used ash instead.

> Also, it's not consistent that the function emits a compiler warning,
> but at the same time isn't labelled as deprecated.

We don't necessarily want consistency of that kind, not in all cases,
anywhere.  If you've read the discussion of the above bug, you've seen
the reasons for not deprecating it.

> If there are still valid uses, then there shouldn't be a warning. If
> not, it should be deprecated. The current status doesn't make sense
> IMHO.

Well, we obviously disagree.

And if this still doesn't convince you, then let's agree to disagree.

Re: lsh function documentation

[Ulrich Mueller]

>>>>> On Wed, 31 Jan 2024, Eli Zaretskii wrote:

>> It's not clear to me what the message "most uses turn out to be
>> mistakes" tries to communicate. Was it a mistake to use lsh in code
>> written in the pre-bignum era?

> Most uses of it, yes.  They should have used ash instead.

Only in hindsight, I suppose? Nothing in the old (i.e. pre-bignum)
documentation suggests any preference for ash.

Ulrich

Re: lsh function documentation

[Eli Zaretskii]

> From: Ulrich Mueller <ulm@gentoo.org>
> Cc: emacs-devel@gnu.org
> Date: Wed, 31 Jan 2024 18:01:17 +0100
> 
> >>>>> On Wed, 31 Jan 2024, Eli Zaretskii wrote:
> 
> >> It's not clear to me what the message "most uses turn out to be
> >> mistakes" tries to communicate. Was it a mistake to use lsh in code
> >> written in the pre-bignum era?
> 
> > Most uses of it, yes.  They should have used ash instead.
> 
> Only in hindsight, I suppose? Nothing in the old (i.e. pre-bignum)
> documentation suggests any preference for ash.

We consider the latter to be a problem, now fixed.