unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
* lsh function documentation
@ 2024-01-30 11:34 Ulrich Mueller
  2024-01-31 14:49 ` Eli Zaretskii
  0 siblings, 1 reply; 6+ messages in thread
From: Ulrich Mueller @ 2024-01-30 11:34 UTC (permalink / raw)
  To: emacs-devel

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? 



^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: lsh function documentation
  2024-01-30 11:34 lsh function documentation Ulrich Mueller
@ 2024-01-31 14:49 ` Eli Zaretskii
  2024-01-31 16:15   ` Ulrich Mueller
  0 siblings, 1 reply; 6+ messages in thread
From: Eli Zaretskii @ 2024-01-31 14:49 UTC (permalink / raw)
  To: Ulrich Mueller; +Cc: emacs-devel

> 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.



^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: lsh function documentation
  2024-01-31 14:49 ` Eli Zaretskii
@ 2024-01-31 16:15   ` Ulrich Mueller
  2024-01-31 16:48     ` Eli Zaretskii
  0 siblings, 1 reply; 6+ messages in thread
From: Ulrich Mueller @ 2024-01-31 16:15 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: emacs-devel

>>>>> 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



^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: lsh function documentation
  2024-01-31 16:15   ` Ulrich Mueller
@ 2024-01-31 16:48     ` Eli Zaretskii
  2024-01-31 17:01       ` Ulrich Mueller
  0 siblings, 1 reply; 6+ messages in thread
From: Eli Zaretskii @ 2024-01-31 16:48 UTC (permalink / raw)
  To: Ulrich Mueller; +Cc: emacs-devel

> 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.



^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: lsh function documentation
  2024-01-31 16:48     ` Eli Zaretskii
@ 2024-01-31 17:01       ` Ulrich Mueller
  2024-01-31 19:27         ` Eli Zaretskii
  0 siblings, 1 reply; 6+ messages in thread
From: Ulrich Mueller @ 2024-01-31 17:01 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: emacs-devel

>>>>> 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



^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: lsh function documentation
  2024-01-31 17:01       ` Ulrich Mueller
@ 2024-01-31 19:27         ` Eli Zaretskii
  0 siblings, 0 replies; 6+ messages in thread
From: Eli Zaretskii @ 2024-01-31 19:27 UTC (permalink / raw)
  To: Ulrich Mueller; +Cc: emacs-devel

> 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.



^ permalink raw reply	[flat|nested] 6+ messages in thread

end of thread, other threads:[~2024-01-31 19:27 UTC | newest]

Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2024-01-30 11:34 lsh function documentation Ulrich Mueller
2024-01-31 14:49 ` Eli Zaretskii
2024-01-31 16:15   ` Ulrich Mueller
2024-01-31 16:48     ` Eli Zaretskii
2024-01-31 17:01       ` Ulrich Mueller
2024-01-31 19:27         ` Eli Zaretskii

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).