From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Drew Adams 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 14:34:28 +0000 Message-ID: References: <83y1jga0nr.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="36520"; mail-complaints-to="usenet@ciao.gmane.io" Cc: "64656@debbugs.gnu.org" <64656@debbugs.gnu.org> To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sun Jul 16 16:35:27 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 1qL2qN-0009FG-9z for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 16 Jul 2023 16:35:27 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qL2q0-0003WR-Lf; Sun, 16 Jul 2023 10:35:04 -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 1qL2py-0003Vy-6k for bug-gnu-emacs@gnu.org; Sun, 16 Jul 2023 10:35:02 -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 1qL2px-000807-RM for bug-gnu-emacs@gnu.org; Sun, 16 Jul 2023 10:35:01 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1qL2px-0005mY-Mu for bug-gnu-emacs@gnu.org; Sun, 16 Jul 2023 10:35:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 16 Jul 2023 14:35:01 +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.168951807922170 (code B ref 64656); Sun, 16 Jul 2023 14:35:01 +0000 Original-Received: (at 64656) by debbugs.gnu.org; 16 Jul 2023 14:34:39 +0000 Original-Received: from localhost ([127.0.0.1]:48375 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qL2pb-0005lW-8A for submit@debbugs.gnu.org; Sun, 16 Jul 2023 10:34:39 -0400 Original-Received: from mx0b-00069f02.pphosted.com ([205.220.177.32]:57634) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qL2pX-0005lJ-R0 for 64656@debbugs.gnu.org; Sun, 16 Jul 2023 10:34:37 -0400 Original-Received: from pps.filterd (m0246632.ppops.net [127.0.0.1]) by mx0b-00069f02.pphosted.com (8.17.1.19/8.17.1.19) with ESMTP id 36GCUGa9007148; Sun, 16 Jul 2023 14:34:34 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=from : to : cc : subject : date : message-id : references : in-reply-to : content-type : content-transfer-encoding : mime-version; s=corp-2023-03-30; bh=y3W5fi0O6JE/YbxN7QJRDCjrp1xOP3pOiipijDHiwCw=; b=oWhWRM4wWfgVL3GzVHBzcZhSIT4PTRB5aDclO8OEFzSOQx/mjQW71caTx9p0VIqHJnse qjFodYPYuwtk51kuYbW9BiedDeYd/H5tk1x6vpiZuRAJzxClrzyZGhPpRO6hv3PKgam5 PI+LYd3AxE8javtvwkEYwY0WBmJWmgG0DA0Ll/sFr3vXn7nkeISoJyC9RWNacEZ8EC97 Q4NMMt3KeRJuFXnNBYShOEPaIHN11It+jEoCyb8RjIkFqPTU4BmSIZXny0rH+XzCMDTG fvPGg8/KuSWIrHH7k/mTN52AUd7XHyoaGK1/gBW2gYVJE3FpZVIT23MPKU1ucXjgkn/O uw== Original-Received: from phxpaimrmta03.imrmtpd1.prodappphxaev1.oraclevcn.com (phxpaimrmta03.appoci.oracle.com [138.1.37.129]) by mx0b-00069f02.pphosted.com (PPS) with ESMTPS id 3run789apw-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Sun, 16 Jul 2023 14:34:34 +0000 Original-Received: from pps.filterd (phxpaimrmta03.imrmtpd1.prodappphxaev1.oraclevcn.com [127.0.0.1]) by phxpaimrmta03.imrmtpd1.prodappphxaev1.oraclevcn.com (8.17.1.19/8.17.1.19) with ESMTP id 36GBIogS019401; Sun, 16 Jul 2023 14:34:33 GMT Original-Received: from nam02-sn1-obe.outbound.protection.outlook.com (mail-sn1nam02lp2048.outbound.protection.outlook.com [104.47.57.48]) by phxpaimrmta03.imrmtpd1.prodappphxaev1.oraclevcn.com (PPS) with ESMTPS id 3ruhw321r0-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Sun, 16 Jul 2023 14:34:33 +0000 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=eDiK1x7tS9TLZIEWls9UekAvvzdzHw1kerlKQq5fUFpccuewFl4D5NmjzJWnDsQSZTDzY5rUtUSZvjpnvkeXs6Uqq/dvLceZ/3kXkLX5Au81qiYDMi3jbDYzcf/9W90crN4jBsKkaK7bgK8dYqw8e+XZN8lkkzJ/IynmEXjUaV5gbakkmBIRZIoG69PwS71+z13H5ltJOXJvhI2fGeZxyFnIviVgg16Nz/Pm1ulBm40sPGQxjmjbqJIABs0xH0/ajYKRwUC0Lb6ZPrqFuA2t6pInUhpFDu6eAaxHWK1/MWVO0EfpYn76F9kdJ37q0W64tHQ/AdNXcKTsf5GTPLnTbw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=y3W5fi0O6JE/YbxN7QJRDCjrp1xOP3pOiipijDHiwCw=; b=MV8O5Mb/A8elIMXtV/tAbSjYNeak+OEBQa1J5opBbUfu7sYtJai3JS2tunjg3gwlz1cmhsKaVgkQJOL902NcLhF6Ip3ABMohPWGru2SddfU7G4s7W2EsAiWvr1vSlB6WtR3Z3Kf+SiMPSshavPRyGGTEh1oaIlgukmJJgbjF6cpWkzgu9jqU43K+LCEazofuRJIBIdvVOHa/u/OnmWhGOtgbKjxkAagclOQFSZIndJ7AOMHf9K6KgGAoi1x4BVuEywWLQWaguLgXYVr1iUIm/xuJVwmikSIi0DFvLbyY+0DR7ZchQxQUzJzwacJLa5fgJCQNZUF/SjDpTE67RUZBNg== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=oracle.com; dmarc=pass action=none header.from=oracle.com; dkim=pass header.d=oracle.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.onmicrosoft.com; s=selector2-oracle-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=y3W5fi0O6JE/YbxN7QJRDCjrp1xOP3pOiipijDHiwCw=; b=b2TIMuiyp/4lnBnCfj3NND/+oG0YCwcSz+lDB5JU+BVcIwSomXZDUFODXIYVjnWsrDevuKXWeF22pTEQHMsXDSqgg+8Zs8c67ntrk9eyBzHFG7Dz9jtHyjK68CZOrdwxT21jQwQHnORL9rzZziLY0e380YH05Gq/hr9OjpaCkyE= Original-Received: from SJ0PR10MB5488.namprd10.prod.outlook.com (2603:10b6:a03:37e::19) by PH7PR10MB5698.namprd10.prod.outlook.com (2603:10b6:510:126::18) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6588.31; Sun, 16 Jul 2023 14:34:28 +0000 Original-Received: from SJ0PR10MB5488.namprd10.prod.outlook.com ([fe80::3d70:a351:b27b:812a]) by SJ0PR10MB5488.namprd10.prod.outlook.com ([fe80::3d70:a351:b27b:812a%3]) with mapi id 15.20.6588.028; Sun, 16 Jul 2023 14:34:28 +0000 Thread-Topic: [External] : Re: bug#64656: 29.0.91; Doc of minibuffer histories and completing-read - automatic addition of completions to DEFAULT list Thread-Index: Adm3dQO6x7fUknP/Q4+io7P97PcUXgAMM39VABGDlJA= In-Reply-To: <83y1jga0nr.fsf@gnu.org> Accept-Language: en-US Content-Language: en-US x-ms-publictraffictype: Email x-ms-traffictypediagnostic: SJ0PR10MB5488:EE_|PH7PR10MB5698:EE_ x-ms-office365-filtering-correlation-id: bdb512ff-54df-49fa-783c-08db8609c2cb x-ms-exchange-senderadcheck: 1 x-ms-exchange-antispam-relay: 0 x-microsoft-antispam: BCL:0; x-microsoft-antispam-message-info: RFIpt1J0ncUdDhYHLQIoRsKqU05rVRLBEv3YTRwoNDTGk3v66AsUqkN8p5xD1Znb0+CPGt9ODH0Rx5ULOlYpOSYpNiIQ/iOua9H6LHKIpLhEb7zrKDJbL2aXgvP+iBynA2x54UCETqYOjq5b96h7/sjjFdBWaaHBVEzNDgtoEhPThCz09omT6Hi3uatP9d/mWDynoJ0vyD5dLmGsJDOQuOt9Kwg5udZEB0VJ/zFAq6VxqY5tJfox6G4jTI4Yuv8YJtwDwPh72bgsLUIu++uVPYtepkrh/2YxajLTGA+ynfn/Qqx2tAaH5F/ciWuj7Xo5McAytGihgAwJoRkzwX8FkUrIj0yI1//0SJZ3MRlwmsoENPTVkrg20JTauaoR0zhWgPPKkmFN7Gslb4oINRIwvgcBo2UG7KLXY7F4FTYhT1olUBFnD3mFrbH4gcuemoN5WwnAV8EwpMM/wvdg1yt5JdUFIMnvTvmUOy3TnXLSId8zjVY2g6daYDD/VqeI28sPhn5KNDY8QF/Dx64G+LThqjsZzTZbRGqBwx0ba1u1ec2bt8pvKHc34oPmPuOgu3bXSinQXpgalIuyaOLWrXQuPFojk5AXSc+PYWLXh0AI8x2k1wi5Y40Ncu4r9Mng2qJn x-forefront-antispam-report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:SJ0PR10MB5488.namprd10.prod.outlook.com; PTR:; CAT:NONE; SFS:(13230028)(366004)(136003)(376002)(39860400002)(346002)(396003)(451199021)(2906002)(55016003)(38100700002)(122000001)(9686003)(83380400001)(186003)(26005)(6506007)(33656002)(86362001)(52536014)(38070700005)(5660300002)(8936002)(8676002)(44832011)(478600001)(7696005)(71200400001)(316002)(41300700001)(4326008)(64756008)(66476007)(66556008)(66946007)(6916009)(66446008)(76116006); DIR:OUT; SFP:1101; x-ms-exchange-antispam-messagedata-chunkcount: 1 x-ms-exchange-antispam-messagedata-0: eO5akWRBmJSGRuzQwaerXPZ7QOKHxn6jf823sqPhp+tG/gFG7HXeTuo83W3gRnqs44gu3cN6+kvSjDTCJK7BD8ZJQyZal6+39ZjewjkH2bHf16t/A8JczlKEYlP2OPPPgzUV8EjgPKFOhhH4Dxw8SLRFZq2rXmQg522B7ti0r970+A7m8c2qtrBPd7WGTaLaWiy3Xd0wbszmPomWosqQLrAgmYuuPOe1rDJZT/1HBZwJUpv1p/l+L1CH6irwpC7XNFtAe9zo0r70k7RoKy3NfsFTkF4cHRWNQzJUSWnQgr44LsL1U9zivEU2nHaujBN/+lJYaalb2Wv9snBeZg0jYBcRSXxu/Evl+vvAahWHLciWygEcajzBblRPRancarDnR6LY5awIxRDapDOdLffSKrfYVL+nWUjmRbWJKgia+WTBNF5jLq/DSxwmMf2080WUVZr+WrF1B7k0luM3nn4TSKzf9XefIAPkSTxRXXvEchmZx/ihZ8Xa7hA+Rb96CESR2ph8Qcmjsn1CxJMeYfLedB6Mp+a53xEqX/nebIa+QQHdZyRMceuouzkMnZPk/c248WIy5CgxO8DrG42nLitBTknecyL3KEudM7TbNdz1+q3Q5PY3XJb05VTFJNdCCckiHF4NLz7JHtR1EVWnHyqK2Jyb+L0MPMI/qqxgNs0qxTBd8hedH6eqi4TiW+e6SJl+vsBgB+kuOmxFFWyarQC8xkAkrub9AQgBpM8J3YpiWQV9i7IzP8sA1rVCNs JNS7tm0SUqaJsE0aDVGA8No0TUUod5oQw6Pojq5BC52UH1sXSJsYsM5wtTD660pJw0m3ULJdKoDaL8l5TKhif3RLalH0tbNIpM X-MS-Exchange-AntiSpam-ExternalHop-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-ExternalHop-MessageData-0: BVKuYBWnMjrIgv9RY8OaSmlI0T/K/jcLobREQy0FvIZ73a2TgE9DoVmHpFkSin5fqARTL7TagbgxyZ9VJDqjlbLcnIHTXpBmEZTMufxsWLTdrQ9X0xim3dzAGfPCOXAhJ5e7onvOwcYsB07bxMjp93YtZYdSt+9ZQA3gulRekwi35K8qiXuvrK5XYs3jqXEu4oK/PHzdr+Nf1zIOX2ZbMbagjWoFy17sBbfHVRkqsxgMXjKAsfPHt4ySIjqpAj8WDIRviVc/EgQYsqaCImC+y99R9+CZ7CtLThW8DlNWn5sJCMmBpbg+2h4Pd/ecCuUQYoRXwuDM0FFqVdsrqnibVa6k+DxPtiNdpNJoerBO7FhZiI7yrK1Vn2OnTEilToKSvFnsFzL1uj6Mnx2hFdFGLwGuaZjzlw5iaAsmaV32alS3GUMTVfgXESJMXiMe23ue7V53zChCqzOmn7bIu+vnn28/QQAsU5Ws+VEniiG6mT6LaTOc6oFP/JXZN/urAr2dUJk/IHbhoX7DJ4x9+B36AN+4Bdx+di2Gk7G17SjQAi1QugcRHKPnP4DNPOXUcSDwSu9OJjtZm0JL5n2QrXmw1SKIcM4Qv8yqCRp4z4LP4RGLO58TKR1PFWpF8g9uUYlFcaNnIcOZ5KEDdxn/82TuTmS5fq6t5nTqFFrUi5hcMY1Fx6cfVzgoEG8gP/7IIWH33x4qKbto+lnBEeQuiqnXBKdSYb2xtSduBCuY7eDRFQUQco tEccnHnW7qWVQJfj35unu7t3oW3FJOUiIYGwPelm4tGkF+q0rqyc/D18LZKJA= X-OriginatorOrg: oracle.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-AuthSource: SJ0PR10MB5488.namprd10.prod.outlook.com X-MS-Exchange-CrossTenant-Network-Message-Id: bdb512ff-54df-49fa-783c-08db8609c2cb X-MS-Exchange-CrossTenant-originalarrivaltime: 16 Jul 2023 14:34:28.3955 (UTC) X-MS-Exchange-CrossTenant-fromentityheader: Hosted X-MS-Exchange-CrossTenant-id: 4e2c6054-71cb-48f1-bd6c-3a9705aca71b X-MS-Exchange-CrossTenant-mailboxtype: HOSTED X-MS-Exchange-CrossTenant-userprincipalname: CQFbgRGXVxWdTKy/Rk86ps8aJ5BAhBMXVm6pcmY8gYMC+mdJ17QtPjWkI9TmxKOUIIHxo1Q99/ItXomuZXuRoA== X-MS-Exchange-Transport-CrossTenantHeadersStamped: PH7PR10MB5698 X-Proofpoint-Virus-Version: vendor=baseguard engine=ICAP:2.0.254,Aquarius:18.0.957,Hydra:6.0.591,FMLib:17.11.176.26 definitions=2023-07-16_02,2023-07-13_01,2023-05-22_02 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=0 malwarescore=0 mlxscore=0 adultscore=0 spamscore=0 phishscore=0 bulkscore=0 mlxlogscore=999 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2306200000 definitions=main-2307160138 X-Proofpoint-ORIG-GUID: CpdvvhDyCeZLk2WepVJZvIJCRfo-bmFL X-Proofpoint-GUID: CpdvvhDyCeZLk2WepVJZvIJCRfo-bmFL 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:265344 Archived-At: > > In sum, important user-visible behavior isn't described in the manual o= r > > the "top-level", most-relevant doc strings (e.g. `completing-read'). >=20 > 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. There are two kinds of doc changes I'd like to see: 1. Elisp manual and Lisp description in doc strings (e.g. `completing-read', `*-history-element'). The behavior isn't documented, AFAICT. It would also make sense, I think, to say something about the "future history" in node (elisp) `Minibuffer History' - how it gets filled automatically with all of the initial completion candidates, unless you bind `minibuffer-default-add-function' to nil (or another non-function value). 2. Emacs manual and user/interactive description in doc strings. I guess I'd like to at least see #1. It isn't at all obvious what's going on. Functions such as `completing-read' give you a way to control the default or defaults provided for `M-n', but they DON'T give you a way to prevent the automatic addition of ALL of the initial completion candidates. To me that doesn't make much sense, but Lispers should at least be told this up front. Let's at least tell them they can prevent this automatic addition by binding `minibuffer-default-add-function' to nil _around_ a function such as `completing-read'. #2 is presumably less important, as long as we don't expose variable `minibuffer-default-add-function' (or similar) as a user option. E.g., currently there's no way for a user to turn off this automatic addition to the `M-n' defaults. The user visible behavior is that `M-n' inserts a default value specific to the command, OR, if var `minibuffer-default-add-function' is non-nil, a "default" value which can be ANY value from the initial completion "domain". E.g., for `C-h v' that means the name of ANY variable (source is obarray filtered for vars). And there's no user or Lisp control over the order of those additional defaults. E.g., `C-h v' adds at most a single "real" default for `M-n', and it adds ALL vars (from obarray). For the Emacs manual, node `Minibuffer History' is a good place to mention this automatic behavior that's governed by a variable. That's where "future history" is introduced for `M-n'. (FWIW, I'm not a fan of the name "future history", instead of what it used to be called: just "defaults".) There we mention where the defaults added to "future=20 history" come from, but only for file-name input. And in that case we go into detail, mentioning how to turn off this automatic addition (the variable for this is even a user option, unlike the general case, with `minibuffer-default-add-function'). > 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? If you want to understand the Lisp code then you need this info. I guess that's my main concern. If, as a user, you want to get an idea what the `M-n' values are with, e.g., `C-h v', after seeing them present themselves in a seemingly random order, then you'd maybe like to know something about what they are and where they come from. You might just wonder if you can turn off their inclusion, since they kinda represent noise (zillions of variables in obarray, presented in no order understandable to users). Hope this clarifies the request/bug report. ___ Beyond this doc concern, I'll maybe also request (separately, in an enhancement request) that Lispers have some way to control at least the order of these "defaults" that get automatically added for `M-n'. E.g., be able to sort the obarray or list.