From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.bugs Subject: bug#75290: Fwd: remove-pos-from-symbol and bare-symbol Date: Sun, 5 Jan 2025 16:08:35 +0000 Message-ID: References: Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="31659"; mail-complaints-to="usenet@ciao.gmane.io" Cc: acm@muc.de, 75290@debbugs.gnu.org, rms@gnu.org To: Stefan Kangas Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sun Jan 05 17:09:30 2025 Return-path: Envelope-to: geb-bug-gnu-emacs@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 1tUTBx-00083M-IJ for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 05 Jan 2025 17:09:29 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tUTBZ-000064-Fm; Sun, 05 Jan 2025 11:09:05 -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 1tUTBW-00005v-VY for bug-gnu-emacs@gnu.org; Sun, 05 Jan 2025 11:09:03 -0500 Original-Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1tUTBW-0005yB-MR for bug-gnu-emacs@gnu.org; Sun, 05 Jan 2025 11:09:02 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=debbugs.gnu.org; s=debbugs-gnu-org; h=From:In-Reply-To:MIME-Version:References:Date:To:Subject; bh=dGwCh7F+026XkUQ8jRRS+Iagh20pJfFpddmsqPUChe4=; b=Ix0B5+xaCQs/cMWStXYbShd6ZzEebCLPoatk6tnmfS6Jqp7BzGFpVV6qVLWxLMaKRr8R4BWuMKdP4jPI8891SLQ53CvtV/OIf6L+i3Lt8cXOV0qeAgC4g2zCvR9+rEIsjuMTjemQGgrjeupYLYy1d8AJwqYPQqYO80hbZkmgWQ0WwyJqf1zJnKuFjXOUqd+ueDYS55anRQ8qRBc2frfMJB9t4SsTGcc5dt8AmpUTw+dxMLfsbX0VAYPiXFmFZlOycVRn5xAnn5UTtiZ4tHA3jkhhCQAyd1RsT8u30LjLuS1wLW2EsvoBztG06Oo70oaEdSIyjGNtf5gILD38dmTZjQ==; Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1tUTBW-000381-B3 for bug-gnu-emacs@gnu.org; Sun, 05 Jan 2025 11:09:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Alan Mackenzie Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 05 Jan 2025 16:09:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 75290 X-GNU-PR-Package: emacs Original-Received: via spool by 75290-submit@debbugs.gnu.org id=B75290.173609332712001 (code B ref 75290); Sun, 05 Jan 2025 16:09:02 +0000 Original-Received: (at 75290) by debbugs.gnu.org; 5 Jan 2025 16:08:47 +0000 Original-Received: from localhost ([127.0.0.1]:34895 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tUTBG-00037U-KX for submit@debbugs.gnu.org; Sun, 05 Jan 2025 11:08:47 -0500 Original-Received: from mail.muc.de ([193.149.48.3]:48121) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1tUTBE-00037E-9d for 75290@debbugs.gnu.org; Sun, 05 Jan 2025 11:08:45 -0500 Original-Received: (qmail 60211 invoked by uid 3782); 5 Jan 2025 17:08:36 +0100 Original-Received: from muc.de (p4fe153b2.dip0.t-ipconnect.de [79.225.83.178]) (using STARTTLS) by colin.muc.de (tmda-ofmipd) with ESMTP; Sun, 05 Jan 2025 17:08:36 +0100 Original-Received: (qmail 4104 invoked by uid 1000); 5 Jan 2025 16:08:35 -0000 Content-Disposition: inline In-Reply-To: X-Submission-Agent: TMDA/1.3.x (Ph3nix) X-Primary-Address: acm@muc.de X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:298573 Archived-At: Hello, Stefan. Thanks for the Cc:. On Thu, Jan 02, 2025 at 11:22:44 -0600, Stefan Kangas wrote: > Severity: wishlist > I'm forwarding this to the bug tracker so that we don't lose track of > it. Alan, any comments here? Yes. I remember vaguely having some difficulty formulating these doc strings. Making them accurate would have made them less readable. So I erred on the side of sketchy rather than unreadable. I underestimated the amount of difficulty this would cause. > -------------------- Start of forwarded message -------------------- > From: Richard Stallman > To: emacs-devel@gnu.org > Subject: remove-pos-from-symbol and bare-symbol > Date: Sun, 10 Mar 2024 22:39:23 -0400 > [[[ 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. ]]] > The doc string of remove-pos-from-symbol says to compare it with > bare-symbol. The doc strings are too sketchy to make clear what the > difference is. Someone who knows should make that clear. > Is the difference what they do to an argument that is not a symbol? Yes. bare-symbol signals an error, remove-pos-from-symbol returns a non-symbol argument unchanged. > If so, it would be good to state that explicitly in the doc string > of bare-symbol. "If need be" is not explicit, not concrete. OK. The current doc string for bare-symbol is: Extract, if need be, the bare symbol from SYM. SYM is either a symbol or a symbol with position. Ignore `symbols-with-pos-enabled'. How about the following replacement? Extract and return the bare symbol from SYM, when it is a symbol with position. Return SYM unchanged when it is a symbol. Otherwise signal an error. Ignore `symbols-with-pos-enable'. Compare with `remove-pos-from-symbol'. > I tried looking at the macros they call, which are in lisp.h. But > those don't have doc strings and just call other functions that have > no comments to say what they do. > The macros and inline functions in lisp.h need to be documented there. I agree, this is bad and needs rectifying. The time taken to fix this would be less than the time wasted by people reading it and having to figure out for themselves what each macro/function does. When I added symbols with position to this part of lisp.h, I just did so in the style of the existing code, i.e. undocumented. I think somebody should fix it now. > -- > 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) > -------------------- End of forwarded message -------------------- -- Alan Mackenzie (Nuremberg, Germany).