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