From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Eric Abrahamsen Newsgroups: gmane.emacs.bugs Subject: bug#34708: alist-get has unclear documentation Date: Sat, 02 Mar 2019 11:06:39 -0800 Message-ID: <87wolhhz9c.fsf@ericabrahamsen.net> References: <87wolhr5k6.fsf@web.de> <87y35xdu4w.fsf@web.de> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="251755"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) To: 34708@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Mar 02 20:08:40 2019 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1h09zx-0013MD-QS for geb-bug-gnu-emacs@m.gmane.org; Sat, 02 Mar 2019 20:08:37 +0100 Original-Received: from localhost ([127.0.0.1]:57801 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h09zw-0002Ab-QX for geb-bug-gnu-emacs@m.gmane.org; Sat, 02 Mar 2019 14:08:36 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:59094) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h09zT-0001wr-4u for bug-gnu-emacs@gnu.org; Sat, 02 Mar 2019 14:08:07 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1h09zS-00016g-3k for bug-gnu-emacs@gnu.org; Sat, 02 Mar 2019 14:08:07 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:44317) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1h09zO-00012d-1h for bug-gnu-emacs@gnu.org; Sat, 02 Mar 2019 14:08:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1h09zN-0001Aw-R1 for bug-gnu-emacs@gnu.org; Sat, 02 Mar 2019 14:08:01 -0500 X-Loop: help-debbugs@gnu.org In-Reply-To: Resent-From: Eric Abrahamsen Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 02 Mar 2019 19:08:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 34708 X-GNU-PR-Package: emacs X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.15515536224450 (code B ref -1); Sat, 02 Mar 2019 19:08:01 +0000 Original-Received: (at submit) by debbugs.gnu.org; 2 Mar 2019 19:07:02 +0000 Original-Received: from localhost ([127.0.0.1]:57861 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1h09yN-00019O-41 for submit@debbugs.gnu.org; Sat, 02 Mar 2019 14:07:01 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:44477) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1h09yK-00019A-Fb for submit@debbugs.gnu.org; Sat, 02 Mar 2019 14:06:56 -0500 Original-Received: from lists.gnu.org ([209.51.188.17]:53924) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1h09yF-00086r-DP for submit@debbugs.gnu.org; Sat, 02 Mar 2019 14:06:51 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:58859) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h09yE-0001U2-EN for bug-gnu-emacs@gnu.org; Sat, 02 Mar 2019 14:06:51 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1h09yD-000855-Ln for bug-gnu-emacs@gnu.org; Sat, 02 Mar 2019 14:06:50 -0500 Original-Received: from [195.159.176.226] (port=46370 helo=blaine.gmane.org) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1h09yD-00081e-E1 for bug-gnu-emacs@gnu.org; Sat, 02 Mar 2019 14:06:49 -0500 Original-Received: from list by blaine.gmane.org with local (Exim 4.89) (envelope-from ) id 1h09yB-00118R-AB for bug-gnu-emacs@gnu.org; Sat, 02 Mar 2019 20:06:47 +0100 X-Injected-Via-Gmane: http://gmane.org/ Cancel-Lock: sha1:FsLgoyvLKOWv0DH2HMOQ9fIA5ms= X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 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.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:155970 Archived-At: Michael Heerdegen writes: > "Miguel V. S. Frasson" writes: > >> I can't imagine how to *set* anything with alist-get. It seams to me >> that it just use the value of ALIST for look up, so talk about >> generalized variables is meaningless to me here. > > You use it like this: say variable V is bound to an alist, then you can > do (setf (alist-get key V) value). After that, (alist-get key V) will > evaluate to VALUE, so you have "set" that place. In the general case, V > can also be a generalized variable, e.g. (car SOMETHING-ELSE). > > To replace the word "this" with something better is not so easy. We > could write "The name of this function can be used to build expressions > that can be used as a generalized variable", but I doubt it will make > things clearer for somebody not familiar with the concept of generalized > variables. Using this function name to build place expressions is not > different from using other function names that allow to be used for > generalized variables. One other phrase you often see here is "setf-able place". I don't know if that's formally acceptable in docstrings, but it would be much more comprehensible to say "this form is a setf-able place", and would give the key hint (setf) as well. It's true it's pretty weird to refer to a function call as a variable. > I would rather go with an example, which I think is justified because > using this function name in place expressions is the canonical way to > modify alists and people need to use it (there is no `alist-put') no > matter if they are familiar with generalized variables. Most definitely, this needs examples. I also agree that the REMOVE usage needs an example -- I made it work eventually, but it took a fair bit of experimentation. Eric