From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#64656: 29.0.91; Doc of minibuffer histories and completing-read - automatic addition of completions to DEFAULT list Date: Sun, 16 Jul 2023 08:24:56 +0300 Message-ID: <83y1jga0nr.fsf@gnu.org> References: Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="34379"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 64656@debbugs.gnu.org To: Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sun Jul 16 07:25:16 2023 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 1qKuFw-0008jU-Co for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 16 Jul 2023 07:25:16 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qKuFl-0003ul-RZ; Sun, 16 Jul 2023 01:25:06 -0400 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 1qKuFj-0003uY-1T for bug-gnu-emacs@gnu.org; Sun, 16 Jul 2023 01:25:03 -0400 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 1qKuFi-0003Y2-NC for bug-gnu-emacs@gnu.org; Sun, 16 Jul 2023 01:25:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1qKuFi-000300-JU for bug-gnu-emacs@gnu.org; Sun, 16 Jul 2023 01:25:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 16 Jul 2023 05:25:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 64656 X-GNU-PR-Package: emacs Original-Received: via spool by 64656-submit@debbugs.gnu.org id=B64656.168948508111498 (code B ref 64656); Sun, 16 Jul 2023 05:25:02 +0000 Original-Received: (at 64656) by debbugs.gnu.org; 16 Jul 2023 05:24:41 +0000 Original-Received: from localhost ([127.0.0.1]:46387 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qKuFM-0002zO-QO for submit@debbugs.gnu.org; Sun, 16 Jul 2023 01:24:41 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:41778) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qKuFK-0002zA-6J for 64656@debbugs.gnu.org; Sun, 16 Jul 2023 01:24:39 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qKuFE-0003Ka-Go; Sun, 16 Jul 2023 01:24:32 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=mt98snj3UewwXNht2f/N2uoIIXxk6ABjXyCBKLXpSeQ=; b=ZHQX0pfq/wPG BreDJfDer6sKyj3JRjwfoJOWZCGDC84r/NuGQ2ir2g7+BzHHNwqRcIi4fBBV5KGszbl/TFimnKHz6 8fwHubHqiW/k144kjIalv0x4GLjxideXUAEG5s/Mq/snS8yUBVVDmPP68M75CHBMOm4p1aK8A3XGU JhtyucCaoXbXX1SOTyWYLz5h9/GmFskgsvNBhUcQl7YugatznKzOPGV+urVMQVT5gUCAsacgQqbbq /mrSr8cXB83aDpOl5/FT7pQcLPWpZUHRUhwHuYL0OV19WT8TD3nV7fG64+G17SOWqSaVmLe/C5G6U loXFeNzRDw3hoLJI9ipKAg==; Original-Received: from [87.69.77.57] (helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qKuFE-0003kT-0s; Sun, 16 Jul 2023 01:24:32 -0400 In-Reply-To: (message from Drew Adams on Sat, 15 Jul 2023 23:35:20 +0000) 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:265266 Archived-At: > From: Drew Adams > Date: Sat, 15 Jul 2023 23:35:20 +0000 > > It seems to me that the doc, including in the Elisp manual, doesn't make > clear that, by default, `completing-read' automatically adds the list of > all completions provided by the completion table to the list of > defaults, just after the default value. That is, by default, it calls > `minibuffer-default-add-completions'. > > This is not obvious from reading the docs. For example, it's not > obvious that if you use `C-h v' and then `M-p', repeating `M-p, you get > the symbols that are variables, one by one, inserted into the > minibuffer. > > How so? Because by default variable `minibuffer-default-add-function' > is `minibuffer-default-add-completions'. Again, none of this is > obvious. To find it out, a user needs to check what `M-p' is bound to, > then check the source code for that function, and then the source code > or the doc string of function `goto-history-element', which it calls. > > In sum, important user-visible behavior isn't described in the manual or > the "top-level", most-relevant doc strings (e.g. `completing-read'). You have described various aspects of the implementation, but no "user-visible behavior" and no reason why it would be interesting, let alone important, to have that in the manual. Please consider changing the POV of your description so that it will be clear what important information is missing and why. The main purpose of API descriptions in the ELisp manual is to explain to Lisp programmers how to achieve this or that behavior, and I cannot bridge the gap between that goal and what you wrote. For starters, this: It seems to me that the doc, including in the Elisp manual, doesn't make clear that, by default, `completing-read' automatically adds the list of all completions provided by the completion table to the list of defaults, just after the default value. That is, by default, it calls `minibuffer-default-add-completions'. is a huge turn-off, because it talks about what the code does. After reading this, I have no idea why I would need to know these details. Why do I care that the list of all completions is added to the list of defaults? why do I care that the code calls minibuffer-default-add-completions? Etc. etc.