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#36500: [External] : Re: bug#36500: 26.2; Minor mode doc strings - say what the current mode-variable value is Date: Tue, 22 Jun 2021 15:10:03 +0000 Message-ID: References: <4dc6d6ce-351c-426a-8371-3ce170c74f1a@default> <87k0mmouwq.fsf@gnus.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="7887"; mail-complaints-to="usenet@ciao.gmane.io" Cc: "36500@debbugs.gnu.org" <36500@debbugs.gnu.org> To: Lars Ingebrigtsen Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Tue Jun 22 17:18:22 2021 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 1lviAQ-0001xh-86 for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 22 Jun 2021 17:18:22 +0200 Original-Received: from localhost ([::1]:40712 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1lviAP-00017d-7O for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 22 Jun 2021 11:18:21 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:49050) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lvi3K-0005zu-89 for bug-gnu-emacs@gnu.org; Tue, 22 Jun 2021 11:11:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:56356) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1lvi3J-0006uA-SE for bug-gnu-emacs@gnu.org; Tue, 22 Jun 2021 11:11:01 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1lvi3J-0001aa-NP for bug-gnu-emacs@gnu.org; Tue, 22 Jun 2021 11:11: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: Tue, 22 Jun 2021 15:11:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 36500 X-GNU-PR-Package: emacs Original-Received: via spool by 36500-submit@debbugs.gnu.org id=B36500.16243746116044 (code B ref 36500); Tue, 22 Jun 2021 15:11:01 +0000 Original-Received: (at 36500) by debbugs.gnu.org; 22 Jun 2021 15:10:11 +0000 Original-Received: from localhost ([127.0.0.1]:39669 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lvi2V-0001ZN-51 for submit@debbugs.gnu.org; Tue, 22 Jun 2021 11:10:11 -0400 Original-Received: from mx0b-00069f02.pphosted.com ([205.220.177.32]:15708) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lvi2S-0001ZD-IQ for 36500@debbugs.gnu.org; Tue, 22 Jun 2021 11:10:09 -0400 Original-Received: from pps.filterd (m0246632.ppops.net [127.0.0.1]) by mx0b-00069f02.pphosted.com (8.16.0.43/8.16.0.43) with SMTP id 15MF8Cgk006473; Tue, 22 Jun 2021 15:10:06 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-2020-01-29; bh=0JjTSrgmFWgCMgj3sdzG2yJaen/llXWNbxqF8ASZcYI=; b=oIMRUWJmO9d2pKr85BhuKuV61UO/StDTbHnGoeYu3/fXR0oYI+/wDdV3Uq0LAEYiBk1G WUGsjUeLTz6O69HrtIpG2o6bAu4k5KmpAMnIDAhssJH0VenMzAH3rPFMCg9tPqtNhYWo 7JkBZxzDbvwi/GmGOjybe9vPIMq74D8fWNWzn3akN/Gtbg9YWmX1MSnm30umPbSlYm1m 7Y4s9bRdt8lYKfLh6fMs3QDVZIs9X4Yfb+dvdZeBtq+bcfj7GrDEh8ay17eteLZ0IAdS 0+wmvd7EHd8Fs7EYZpdkOgJYzm0Ok8F9NjNuMjwV5UijdsAiQtHYMxE9qofugqbyH+kk Fg== Original-Received: from aserp3020.oracle.com (aserp3020.oracle.com [141.146.126.70]) by mx0b-00069f02.pphosted.com with ESMTP id 39b98v9eq9-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Tue, 22 Jun 2021 15:10:06 +0000 Original-Received: from pps.filterd (aserp3020.oracle.com [127.0.0.1]) by aserp3020.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 15MF9RJ4147656; Tue, 22 Jun 2021 15:10:05 GMT Original-Received: from nam04-mw2-obe.outbound.protection.outlook.com (mail-mw2nam08lp2172.outbound.protection.outlook.com [104.47.73.172]) by aserp3020.oracle.com with ESMTP id 3998d7n3qe-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Tue, 22 Jun 2021 15:10:05 +0000 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=gZSqSWqTLEgpq0FY7R3SUcUo0gChuh1YWpSEnJM8anXseCVQ0lfAlfSqy6vOlBhlCHyP7ITMGrMZHjcRPcL8CYX7/zyUiRIaRbyvWkczBPJucLIcbgR41kthE9xpP+s/SM39oLsnCp0ghipiSRRkhAIVi3hw5yP7uOVHNGzf2vRipvrmi+GPhsBRrBC5JOUCvv86gvtil9GvHDp0ivg9XpiWDxWMB9cPk2cROcw4xm+eBGitTbl8Zzq8d+nANqjigeP0btzHvXv4VEtR2jVWzyLxGJqe8E9vDydoDkn6xOUoaBaAjRu1bnCf/F+nWGUiI+9t1hdgAk5HsBXuK9zafQ== 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-SenderADCheck; bh=0JjTSrgmFWgCMgj3sdzG2yJaen/llXWNbxqF8ASZcYI=; b=fOPQHcg2warAMXvdOPL+CULgauFtUFk+KsdqT8aSic+T6yeYLKePtDiAVKHbdiU7PXwImCqDYG5Pihfvz6JFQkWuJppfDBp4BuYL12DMTd9Qcqsw8hhWGVUpZff8akyUcSeUpCD4WOj/eThgMDPdK17gg98JWUFhBn2thQIwubB/D2m7pPo/hhRQMOTEzoF4W4UGLqX3Tb7oX10pYtp7Z8YCa1KfNrjRLRc6KQwX5pXTzYLhdvajbtQM+Y9/DH1B8MQYscxcUP0SFGdSl0LIZ+haY7YOAprO0P1b94tHRBfrjFLtt/3AHamlJhS9itf77D1vsKRpeJCywa81pmDYCA== 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=0JjTSrgmFWgCMgj3sdzG2yJaen/llXWNbxqF8ASZcYI=; b=cYdmHRLUgJUi6nG3ffT9G3DyIc9Op8xXADx3du+B6Qkz4iqyeNfjdYkVwF6ManJA1JCuAPqvM7Sl9ZpEyNm6yRrX37cAaWCrrs5OzI0VfknNJ99qOHutWbkaUgQXFO/DFbYhg5RBHTnYiqOaj/iJWM1K7WSHSaZhc5h4DrYszdg= Original-Received: from SA2PR10MB4474.namprd10.prod.outlook.com (2603:10b6:806:11b::15) by SA2PR10MB4570.namprd10.prod.outlook.com (2603:10b6:806:11e::9) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4264.18; Tue, 22 Jun 2021 15:10:03 +0000 Original-Received: from SA2PR10MB4474.namprd10.prod.outlook.com ([fe80::1c0e:6d54:3781:bd5c]) by SA2PR10MB4474.namprd10.prod.outlook.com ([fe80::1c0e:6d54:3781:bd5c%6]) with mapi id 15.20.4242.023; Tue, 22 Jun 2021 15:10:03 +0000 Thread-Topic: [External] : Re: bug#36500: 26.2; Minor mode doc strings - say what the current mode-variable value is Thread-Index: AQHXZ2/oup0uCcq+h0uPU7WpVgtbUKsgHmsg In-Reply-To: <87k0mmouwq.fsf@gnus.org> Accept-Language: en-US Content-Language: en-US authentication-results: gnus.org; dkim=none (message not signed) header.d=none;gnus.org; dmarc=none action=none header.from=oracle.com; x-originating-ip: [73.170.83.28] x-ms-publictraffictype: Email x-ms-office365-filtering-correlation-id: 6df12691-90a2-4e7b-dfb4-08d9358fcfc5 x-ms-traffictypediagnostic: SA2PR10MB4570: x-microsoft-antispam-prvs: x-ms-oob-tlc-oobclassifiers: OLM:10000; x-ms-exchange-senderadcheck: 1 x-microsoft-antispam: BCL:0; x-microsoft-antispam-message-info: DR8ZVQ/eA5or48ogDP0ztuX8IzHWfQ/CqOqmNpGQiICVSgD4eQ47Et45dPLlat3/CgMFViXgjb0+BOiZUnv64mevbM8agM26nLFmoqPP1BM5+HMfK6TKE9Zx63q6ldqLHjZs1qpNVC4R3CoUGM3je56qAEZsRGkPXxRMitJa8cvZyi8ecn03z1Zwj2sQTa6amqdZrBENdARJDadNgCzcGIAhDsKZYyelQKBy+mMuZeGMyTkcKBTswWe6YN8/KmEto3etqMhhnFFi0DT7XqCHcT3D1xRoQl65SFBVJf7HbHHAk0CtRd/ZjMq8iOBCLwisxETKGwfUECtqJtn/7shX21yWLCtEkOZCOrgAfnukZp8LPy6595AOr2UluybvcE62+c7R2O4pb7MHVrf21TRUFGh69paDrhIDPR1HUeBOZf1kyJdniqUtl+jANFWgfthS7MAmlkciJmzGV8YYRK0u+Z8OpMQcwcLZCtrZ1DeVArcvaf0zNPBW7dik/9mC47dXmDaHPwkOisJ3XM5f+ypf/SJv8IbhjhIvaqGaGYJpFpt8Yy2OELNSIRfgJMB46qvaJ2zUag4zmXWnf4vEOaaeeg3sc7KZh14RG7Ru3+mwGds= x-forefront-antispam-report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:SA2PR10MB4474.namprd10.prod.outlook.com; PTR:; CAT:NONE; SFS:(376002)(39860400002)(346002)(366004)(396003)(136003)(66446008)(66946007)(66476007)(66556008)(64756008)(44832011)(2906002)(8936002)(8676002)(316002)(5660300002)(71200400001)(76116006)(52536014)(86362001)(186003)(33656002)(55016002)(9686003)(6506007)(26005)(7696005)(38100700002)(4326008)(6916009)(478600001)(122000001); DIR:OUT; SFP:1101; x-ms-exchange-antispam-messagedata-chunkcount: 1 x-ms-exchange-antispam-messagedata-0: zDl/Mh/wfmLaLUuLxStImQA2BoUT+bpyygeKJ0q0rAEkZ3mcSZBwT2uGPiOjcwu3A1Y8G1+0yOkTxSXILG7+zP9RqLRXFgFM7jb7iHC1IPWBAYZM3eoaMe3ot3g/+pEL6nCYOeW2eIw6of+Q7CQpSaDNCo3kl5OR1RjL0D7mG8knXdu++8vhjCjwMaX/esRI81Pd+C7AYXkI3MuSeU/x48sw/z8uR4/P7bSSwtIVNvHGS/ObljcVBGxT41rc6LkKWi2T6Vs/SHrPrwbsaqsCxbAJC0rCIK4JAPOb4Dw2jVc77BE6mR2/XA0CR46pYlWLEGqMtvnnNjrVMO1gq+9k/QTet6bmhDjcdM5SZWh/amTm16B3IODXWBCFqAVdkSM3oFT3v8LmB1EbFw4FvjaPLh1+dSWQ4nGBlYYsPPwZ0KFn1gyfIZyXUdF0NKTvD9+lSiEPZCS3tyIraLbugrZmiBg97FICwRCYCPZOql/yFV9UPGnm08RwT0yWQahanJjZ0ClNYJCUDO6Uha5m3LVy9/2GlEFZQPvmT4/T1SxuPVXPtQ34mVym88jJA1RZQ+6Em6KIRtj4so5/Zr9NSJggEG8iCx4zEpErHKx3xXUkNIh9sHU6V7NFugnJIvp5klsxrC+KY7t0LEhFlQupmVP8LvrwC918FQC83MaocpvaILy9UlSwrdULn2I6D/K8GPAu3Y3QgEpjbcIY6ASWA239AA0Koai8rXZSUChHqOaGur9wpOhvZYPKMFfDU8 dugSXFCZKjTVhjqM3FGMPDdy5DzP9rgvFw46Hx0o5Kpz4cJtXBtjq+0snAe4Qps7Ma+ZmYA2lxzRzT5TxzI2k48pxXS1C+hO2U x-ms-exchange-transport-forked: True X-OriginatorOrg: oracle.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-AuthSource: SA2PR10MB4474.namprd10.prod.outlook.com X-MS-Exchange-CrossTenant-Network-Message-Id: 6df12691-90a2-4e7b-dfb4-08d9358fcfc5 X-MS-Exchange-CrossTenant-originalarrivaltime: 22 Jun 2021 15:10:03.1505 (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: dCpA8cif47eJr/BB7Y7N6389oXKtrjQkGIBYtA5HVkUoxZMOzbl8cNePzWkhDAAJVf4GRX4o4jnHKYtJPRUDdw== X-MS-Exchange-Transport-CrossTenantHeadersStamped: SA2PR10MB4570 X-Proofpoint-Virus-Version: vendor=nai engine=6200 definitions=10023 signatures=668682 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 spamscore=0 mlxscore=0 adultscore=0 mlxlogscore=999 phishscore=0 suspectscore=0 bulkscore=0 malwarescore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2104190000 definitions=main-2106220094 X-Proofpoint-ORIG-GUID: mM7KQc_kITtNiDPrPyzV4PGCyIuwjX4H X-Proofpoint-GUID: mM7KQc_kITtNiDPrPyzV4PGCyIuwjX4H 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" Xref: news.gmane.io gmane.emacs.bugs:208869 Archived-At: > > `define-minor-mode' do the following (or at least some of it): > > > > 1. Mention the mode variable (typically the same name as the mode, > > but in any case the name is known to `define-minor-mode'). > > (The doc string currently mentions the keymap, but not the var.) >=20 > I've now done this in Emacs 28. >=20 > > 2. Show the current value of the variable, just as we do for the keymap= . > > If undefined so far then say so, just as we do for the keymap. >=20 > I think that would be pretty odd -- it's just a function doc string, > and the value of these variables in the *Help* buffer is usually nil. Why do you think it would be odd? It would be helpful. The value reported would of course be for the buffer where help was invoked - not for `*Help*' (unless it was invoked there). That's the way `*Help*' works and has always worked. `C-h k ' doesn't tell you the binding in `*Help*'. I'm surprised to see this kind of argument for not documenting something. > > 3. Say whether the variable is global (an option, customizable), or > > buffer-local. >=20 > For minor modes? No, I think that would be counter-productive -- minor > modes should be toggled with the minor mode command. Regardless of your last phrase, which is true in general (but not always), a globalized minor mode DOES create a user option - customizable. Ask yourself why. Help should tell users about it when that's the case. Users shouldn't have to consult the doc for `define-minor-mode' and `define-globalized-minor-mode' each time they ask for help on a minor mode. That's been the problem from the outset, and it's still a problem to some extent. > And besides -- the "mode variable" isn't necessarily a variable: No, not necessarily. All the more reason for Help to tell you what it is. It should tell you when it's a user option, a normal defvar, and a generalized var. > The useful thing, I think, is to have the doc string > document the getter "variable",=20 There is no one "useful thing". Certainly documenting the variable (generalized or not) is important, and it's only one of the things that's important. > so that you know how to check whether the mode is > off or on. Help on the mode should also do that - see the first thing, above. Knowing what the variable is is good. Knowing what the current state is is good. Help on a minor mode should tell you all such things. > so I'm closing this bug report.) Too bad. But at least you presumably made some of the suggested improvements. > > 4. Maybe mention that the variable is set/reset automatically when you > > toggle the mode. If the var is global mention that you can set/rese= t > > it manually using Customize. >=20 > Ditto. Dunno what "ditto" means here. There was some that you did and much that you didn't do. Whether you did #4 isn't clear (without digging out the new code).