From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: =?UTF-8?Q?Sebasti=C3=A1n_?= =?UTF-8?Q?Mon=C3=ADa?= Newsgroups: gmane.emacs.bugs Subject: bug#34842: 26.1; Alist documentation: let-alist Date: Wed, 13 Mar 2019 16:30:16 +0000 Message-ID: References: , <3c296021-c231-4c62-b8e3-0e870cb224cc@default> Mime-Version: 1.0 Content-Type: multipart/alternative; boundary="_000_BN8PR04MB5555A95657B2651F4689FE408B4A0BN8PR04MB5555namp_" Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="122486"; mail-complaints-to="usenet@blaine.gmane.org" To: "34842@debbugs.gnu.org" <34842@debbugs.gnu.org> Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Wed Mar 13 18:42:32 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 1h47tf-000Vhq-UL for geb-bug-gnu-emacs@m.gmane.org; Wed, 13 Mar 2019 18:42:32 +0100 Original-Received: from localhost ([127.0.0.1]:48561 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h47te-0003Ih-Oz for geb-bug-gnu-emacs@m.gmane.org; Wed, 13 Mar 2019 13:42:30 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:41998) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h47pD-0007gp-A4 for bug-gnu-emacs@gnu.org; Wed, 13 Mar 2019 13:37:56 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1h47cl-0003Nr-4B for bug-gnu-emacs@gnu.org; Wed, 13 Mar 2019 13:25:04 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:57129) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1h47ck-0003NY-K7 for bug-gnu-emacs@gnu.org; Wed, 13 Mar 2019 13:25:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1h47cj-00065U-NB for bug-gnu-emacs@gnu.org; Wed, 13 Mar 2019 13:25:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: =?UTF-8?Q?Sebasti=C3=A1n_?= =?UTF-8?Q?Mon=C3=ADa?= Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 13 Mar 2019 17:25:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 34842 X-GNU-PR-Package: emacs Original-Received: via spool by 34842-submit@debbugs.gnu.org id=B34842.155249789923389 (code B ref 34842); Wed, 13 Mar 2019 17:25:01 +0000 Original-Received: (at 34842) by debbugs.gnu.org; 13 Mar 2019 17:24:59 +0000 Original-Received: from localhost ([127.0.0.1]:42440 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1h47cf-000658-Kn for submit@debbugs.gnu.org; Wed, 13 Mar 2019 13:24:59 -0400 Original-Received: from mail-oln040092006041.outbound.protection.outlook.com ([40.92.6.41]:50807 helo=NAM03-BY2-obe.outbound.protection.outlook.com) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1h46ls-0004nI-89 for 34842@debbugs.gnu.org; Wed, 13 Mar 2019 12:30:27 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=outlook.com; s=selector1; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=Pk65wkZXQnHp6O/HKVkIqYJhIubsQlFMFJmsXsvmv3U=; b=e1uP93SQwlYVLfLCT+UPRN+mKUK6kFmPTdpwYJuN25RqJoCFiE5+2FBBJD0+szdZLoZInyx4iCqT048xw7Wr9+wCWDYDfxUdFzq5rnNgFESnIa49pDYxyHU8k/ONQivQ+IH3rJCuPN/Aq9b5SS6bMlETb4pTvlcyFJ2mRgi8AGv8TCSjCyEHoGDTV7BBunpkXL6tksyAPz85kf9H+S06Z5zUyntFgAV/cMrJr2WCb+LeHBTDFK1+V3Iy/aNHyK5hhIICvXAMMvhUyDHhsVlutao1jdI7rh3qB41EpEVb6a5SH9SwHLUoP23Oyfv8YmUMCDJQZ3K66uLLpocWyB1nlQ== Original-Received: from CO1NAM03FT014.eop-NAM03.prod.protection.outlook.com (10.152.80.52) by CO1NAM03HT039.eop-NAM03.prod.protection.outlook.com (10.152.81.45) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384) id 15.20.1686.19; Wed, 13 Mar 2019 16:30:17 +0000 Original-Received: from BN8PR04MB5555.namprd04.prod.outlook.com (10.152.80.53) by CO1NAM03FT014.mail.protection.outlook.com (10.152.80.101) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384) id 15.20.1709.13 via Frontend Transport; Wed, 13 Mar 2019 16:30:17 +0000 Original-Received: from BN8PR04MB5555.namprd04.prod.outlook.com ([fe80::890f:1d5c:65a6:f0d3]) by BN8PR04MB5555.namprd04.prod.outlook.com ([fe80::890f:1d5c:65a6:f0d3%3]) with mapi id 15.20.1686.021; Wed, 13 Mar 2019 16:30:17 +0000 Thread-Topic: bug#34842: 26.1; Alist documentation: let-alist Thread-Index: AQHU2WfoQNkpN7Cxwka7S9tpV8PRbKYJrKYAgAAUn+s= In-Reply-To: <3c296021-c231-4c62-b8e3-0e870cb224cc@default> Accept-Language: en-US Content-Language: en-US x-incomingtopheadermarker: OriginalChecksum:103EA529AD4B56DB7D73510CE8EC58B7324914DA93A97040E6CCB842E8ECAC5D; UpperCasedChecksum:70F4D6616EDD4243D69B5583D8AF069F126749D6B9361CB25A1D3914B0A08AE1; SizeAsReceived:6897; Count:44 x-ms-exchange-messagesentrepresentingtype: 1 x-tmn: [hg3wgY7uFsKs3PSaFvG0GEfiRE6POdaO] x-ms-publictraffictype: Email x-incomingheadercount: 44 x-eopattributedmessage: 0 x-microsoft-antispam: BCL:0; PCL:0; RULEID:(2390118)(7020095)(20181119110)(201702061078)(5061506573)(5061507331)(1603103135)(2017031320274)(2017031323274)(2017031324274)(2017031322404)(1601125500)(1603101475)(1701031045); SRVR:CO1NAM03HT039; x-ms-traffictypediagnostic: CO1NAM03HT039: x-microsoft-antispam-message-info: 1CixYHOLR06ewyo1tAvJq9jykyX5Hurg6Noyg1JL+LzX7RBo64tAlbu8hbUKi5aX X-OriginatorOrg: outlook.com X-MS-Exchange-CrossTenant-RMS-PersistedConsumerOrg: 00000000-0000-0000-0000-000000000000 X-MS-Exchange-CrossTenant-Network-Message-Id: 550c2c20-7d69-46e7-c6cf-08d6a7d12d61 X-MS-Exchange-CrossTenant-rms-persistedconsumerorg: 00000000-0000-0000-0000-000000000000 X-MS-Exchange-CrossTenant-originalarrivaltime: 13 Mar 2019 16:30:17.0539 (UTC) X-MS-Exchange-CrossTenant-fromentityheader: Internet X-MS-Exchange-CrossTenant-id: 84df9e7f-e9f6-40af-b435-aaaaaaaaaaaa X-MS-Exchange-Transport-CrossTenantHeadersStamped: CO1NAM03HT039 X-Mailman-Approved-At: Wed, 13 Mar 2019 13:24:56 -0400 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:156302 Archived-At: --_000_BN8PR04MB5555A95657B2651F4689FE408B4A0BN8PR04MB5555namp_ Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: quoted-printable I thought that the example in the docstring was too long compared to the sm= aller/simpler examples in the rest of the page, but wouldn't be against usi= ng that instead if it's more clear. The nested access example is in .site.contents, maybe being explicit about = which line displays the concept would be a nice improvement. And most of what you said in point 5 is above my level so I will defer to p= eople with more knowledge. Thank you for your feedback Drew! --------------------------------------------------- Why Emacs? http://david.rothlis.net/emacs/why.html From: Drew Adams Sent: Wednesday, March 13, 9:16 AM Subject: RE: bug#34842: 26.1; Alist documentation: let-alist To: Sebasti=E1n Mon=EDa, 34842@debbugs.gnu.org > In [(elisp)`Association Lists'] we should add some > documentation about = [macro `let-alist']. Below a > suggestion. 1. I agree that it might be good= to document this macro in node `Association Lists'. 2. But the example sug= gested is much less clear than the example in the doc string. 3. The exampl= e in the doc string is itself not correct. Instead of "essentially" it shou= ld just show the actual macroexpansion. And it should use a different varia= ble name than `alist'. E.g.: (let-alist my-alist (if (and .title .body) .bo= dy .site .site.contents)) expands to: (let ((alist my-alist)) (let ((\.titl= e (cdr (assq 'title alist))) (\.body (cdr (assq 'body alist))) (\.site (cdr= (assq 'site alist))) (\.site\.contents (cdr (assq 'contents (cdr (assq 'si= te alist)))))) (if (and \.title \.body) \.body \.site \.site\.contents))) (= And yes, the backslashes are necessary.) 4. The last paragraph of the doc s= tring is unclear. What does "access alists inside the original alist" mean?= How is anything it tries to describe "displayed in the example above", whi= ch has NO nesting of `let-alist'? Whatever it might be trying to say, if th= e point of the last paragraph is important, then perhaps an example of such= nesting is called for, pointing out what is meant. Perhaps such a paragrap= h and example don't need to be in both the doc string and the manual (dunno= how important this is, not knowing what it's really trying to say). 5. The= doc (manual and doc string) should explicitly say that `assq' is used, not= `assoc'. It should not just hand-wave about this, saying "search is done".= And it should say what it means by "this search is done at compile time" -= what the consequences of this are. --_000_BN8PR04MB5555A95657B2651F4689FE408B4A0BN8PR04MB5555namp_ Content-Type: text/html; charset="iso-8859-1" Content-Transfer-Encoding: quoted-printable
I thought that the example in the docstring was too long compared to the sm= aller/simpler examples in the rest of the page, but wouldn't be against usi= ng that instead if it's more clear.

The nested access example is in .site.contents, maybe being explicit about = which line displays the concept would be a nice improvement.

And most of what you said in point 5 is above my level so I will defer to p= eople with more knowledge.

Thank you for your feedback Drew!

---------------------------------------------------
Why Emacs? 



From: Drew Adams
Sent: Wednesday, March 13, 9:16 AM
Subject: RE: bug#34842: 26.1; Alist documentation: let-alist
To: Sebasti=E1n Mon=EDa, 34842@debbugs.gnu.org


> In [(elisp)`Association Lists'] we should add some > documenta= tion about [macro `let-alist']. Below a > suggestion. 1. I agree that it= might be good to document this macro in node `Association Lists'. 2. But t= he example suggested is much less clear than the example in the doc string. 3. The example in the doc string is itself not = correct. Instead of "essentially" it should just show the actual = macroexpansion. And it should use a different variable name than `alist'. E= .g.: (let-alist my-alist (if (and .title .body) .body .site .site.contents)) expands to: (let ((alist my-alist)) (let ((\.= title (cdr (assq 'title alist))) (\.body (cdr (assq 'body alist))) (\.site = (cdr (assq 'site alist))) (\.site\.contents (cdr (assq 'contents (cdr (assq= 'site alist)))))) (if (and \.title \.body) \.body \.site \.site\.contents))) (And yes, the backslashes are ne= cessary.) 4. The last paragraph of the doc string is unclear. What does &qu= ot;access alists inside the original alist" mean? How is anything it t= ries to describe "displayed in the example above", which has NO nesting of `let-alist'? Whatever it might be try= ing to say, if the point of the last paragraph is important, then perhaps a= n example of such nesting is called for, pointing out what is meant. Perhap= s such a paragraph and example don't need to be in both the doc string and the manual (dunno how important this= is, not knowing what it's really trying to say). 5. The doc (manual and do= c string) should explicitly say that `assq' is used, not `assoc'. It should= not just hand-wave about this, saying "search is done". And it should say what it means by &quo= t;this search is done at compile time" - what the consequences of this= are.

--_000_BN8PR04MB5555A95657B2651F4689FE408B4A0BN8PR04MB5555namp_--