From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Ulrich Mueller Newsgroups: gmane.emacs.devel Subject: Re: lsh function documentation Date: Wed, 31 Jan 2024 17:15:24 +0100 Message-ID: References: <86y1c51rtu.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="4424"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.2 (gnu/linux) Cc: emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Wed Jan 31 17:16:40 2024 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1rVDGS-0000tK-5y for ged-emacs-devel@m.gmane-mx.org; Wed, 31 Jan 2024 17:16:40 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rVDFi-0006kf-Qa; Wed, 31 Jan 2024 11:15:55 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rVDFZ-0006js-Cr for emacs-devel@gnu.org; Wed, 31 Jan 2024 11:15:52 -0500 Original-Received: from smtp.gentoo.org ([2001:470:ea4a:1:5054:ff:fec7:86e4]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_CHACHA20_POLY1305:256) (Exim 4.90_1) (envelope-from ) id 1rVDFN-0005Go-6s; Wed, 31 Jan 2024 11:15:37 -0500 In-Reply-To: <86y1c51rtu.fsf@gnu.org> (Eli Zaretskii's message of "Wed, 31 Jan 2024 16:49:01 +0200") Received-SPF: pass client-ip=2001:470:ea4a:1:5054:ff:fec7:86e4; envelope-from=ulm@gentoo.org; helo=smtp.gentoo.org X-Spam_score_int: -41 X-Spam_score: -4.2 X-Spam_bar: ---- X-Spam_report: (-4.2 / 5.0 requ) BAYES_00=-1.9, RCVD_IN_DNSWL_MED=-2.3, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.devel:315673 Archived-At: >>>>> On Wed, 31 Jan 2024, Eli Zaretskii wrote: >> From: Ulrich Mueller >> Date: Tue, 30 Jan 2024 12:34:59 +0100 >>=20 >> The function documentation of lsh says: >> | Most uses of this function turn out to be mistakes. We recommend >> | to use =E2=80=98ash=E2=80=99 instead, unless COUNT could ever be negat= ive, and >> | if, when COUNT is negative, your program really needs the special >> | treatment of negative COUNT provided by this function. >>=20 >> 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.tex= i?h=3Demacs-26.3#n811 >>=20 >> So why would programmers who had used something like (lsh x 8) in their >> code be called out for making a mistake? >>=20 >> Couldn't lsh's documentation just say that the function is deprecated >> and that ash should be used instead?=20 > 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