From unknown Fri Aug 15 16:18:57 2025 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-Mailer: MIME-tools 5.509 (Entity 5.509) Content-Type: text/plain; charset=utf-8 From: bug#36500 <36500@debbugs.gnu.org> To: bug#36500 <36500@debbugs.gnu.org> Subject: Status: 26.2; Minor mode doc strings - say what the current mode-variable value is Reply-To: bug#36500 <36500@debbugs.gnu.org> Date: Fri, 15 Aug 2025 23:18:57 +0000 retitle 36500 26.2; Minor mode doc strings - say what the current mode-vari= able value is reassign 36500 emacs submitter 36500 Drew Adams severity 36500 wishlist thanks From debbugs-submit-bounces@debbugs.gnu.org Thu Jul 04 11:19:46 2019 Received: (at submit) by debbugs.gnu.org; 4 Jul 2019 15:19:46 +0000 Received: from localhost ([127.0.0.1]:51730 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hj3WT-0002ZI-Vr for submit@debbugs.gnu.org; Thu, 04 Jul 2019 11:19:46 -0400 Received: from lists.gnu.org ([209.51.188.17]:52032) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hj3WS-0002ZB-Nv for submit@debbugs.gnu.org; Thu, 04 Jul 2019 11:19:45 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:37457) by lists.gnu.org with esmtp (Exim 4.86_2) (envelope-from ) id 1hj3WQ-0004wX-DZ for bug-gnu-emacs@gnu.org; Thu, 04 Jul 2019 11:19:44 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-1.5 required=5.0 tests=BAYES_50,RCVD_IN_DNSWL_MED autolearn=disabled version=3.3.2 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hj3WP-0003sQ-4M for bug-gnu-emacs@gnu.org; Thu, 04 Jul 2019 11:19:42 -0400 Received: from userp2120.oracle.com ([156.151.31.85]:38622) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1hj3WO-0003py-RH for bug-gnu-emacs@gnu.org; Thu, 04 Jul 2019 11:19:41 -0400 Received: from pps.filterd (userp2120.oracle.com [127.0.0.1]) by userp2120.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x64FIhZQ076946 for ; Thu, 4 Jul 2019 15:19:38 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : subject : content-type : content-transfer-encoding; s=corp-2018-07-02; bh=Hb6bB1onm65yOxGH4dM+yM+lH9vP+/ozn+UdQLkMEfE=; b=BE1I3Iyem5A+OrT08ufJKHOuWtG5cfD+FAHKTBS3iSm3nEAyeTFqg+kGG7K/HmjeKZro e72eqN+67V3gl7EdkfuWOEYHPEMDIfPpW5UWZdytOwWey8VZeCTzVYxP5DD6NdJOOpDC MgpIXXwzxi3jrY0gB4oXWXRczLukuBHA1PE788zUcyQdTeDYOVT0WAkPcsaabCo0gQJz 0DFiYpg/8JcLN+Ag8HkpZ+0KGNicd8fhkrev/HBBnhSDiYaHewLI0YxpvyQ3GugUGd1j 7LghiH/k1dYw0rPzH/VpHQYA/B0Yucr3dWHylwnEIHXpwzJppAK8OeJcFy1Tk/i2U2RA DA== Received: from aserp3030.oracle.com (aserp3030.oracle.com [141.146.126.71]) by userp2120.oracle.com with ESMTP id 2te61q7cca-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Thu, 04 Jul 2019 15:19:38 +0000 Received: from pps.filterd (aserp3030.oracle.com [127.0.0.1]) by aserp3030.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x64FHejG098136 for ; Thu, 4 Jul 2019 15:19:37 GMT Received: from aserv0121.oracle.com (aserv0121.oracle.com [141.146.126.235]) by aserp3030.oracle.com with ESMTP id 2th5qmbgx7-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Thu, 04 Jul 2019 15:19:37 +0000 Received: from abhmp0017.oracle.com (abhmp0017.oracle.com [141.146.116.23]) by aserv0121.oracle.com (8.14.4/8.13.8) with ESMTP id x64FJaBj019702 for ; Thu, 4 Jul 2019 15:19:37 GMT MIME-Version: 1.0 Message-ID: <4dc6d6ce-351c-426a-8371-3ce170c74f1a@default> Date: Thu, 4 Jul 2019 08:19:36 -0700 (PDT) From: Drew Adams To: bug-gnu-emacs@gnu.org Subject: 26.2; Minor mode doc strings - say what the current mode-variable value is X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4861.0 (x86)] Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9307 signatures=668688 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=1 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1907040194 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9307 signatures=668688 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 priorityscore=1501 malwarescore=0 suspectscore=1 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015 lowpriorityscore=0 mlxscore=0 impostorscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1907040194 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x [generic] X-Received-From: 156.151.31.85 X-Spam-Score: -1.3 (-) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.3 (--) Apologies if this enhancement request has been proposed before. It seems like it might have been, as it's a pretty obvious possibility. Suggestion: Have the automatically provided part of a minor-mode doc string, from `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.) 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. 3. Say whether the variable is global (an option, customizable), or buffer-local. 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/reset it manually using Customize. 5. Any particularities, e.g. from using `:variable' should be taken into account, so the doc string is correct for all cases. In GNU Emacs 26.2 (build 1, x86_64-w64-mingw32) of 2019-04-13 Repository revision: fd1b34bfba8f3f6298df47c8e10b61530426f749 Windowing system distributor `Microsoft Corp.', version 10.0.17134 Configured using: `configure --without-dbus --host=3Dx86_64-w64-mingw32 --without-compress-install 'CFLAGS=3D-O2 -static -g3'' From debbugs-submit-bounces@debbugs.gnu.org Mon Jul 08 16:42:14 2019 Received: (at 36500) by debbugs.gnu.org; 8 Jul 2019 20:42:14 +0000 Received: from localhost ([127.0.0.1]:59686 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hkaSk-0007ai-7h for submit@debbugs.gnu.org; Mon, 08 Jul 2019 16:42:14 -0400 Received: from quimby.gnus.org ([80.91.231.51]:33358) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hkaSi-0007aa-Eo for 36500@debbugs.gnu.org; Mon, 08 Jul 2019 16:42:12 -0400 Received: from cm-84.212.202.86.getinternet.no ([84.212.202.86] helo=marnie) by quimby.gnus.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1hkaSe-00054R-JK; Mon, 08 Jul 2019 22:42:11 +0200 From: Lars Ingebrigtsen To: Drew Adams Subject: Re: bug#36500: 26.2; Minor mode doc strings - say what the current mode-variable value is References: <4dc6d6ce-351c-426a-8371-3ce170c74f1a@default> Date: Mon, 08 Jul 2019 22:42:08 +0200 In-Reply-To: <4dc6d6ce-351c-426a-8371-3ce170c74f1a@default> (Drew Adams's message of "Thu, 4 Jul 2019 08:19:36 -0700 (PDT)") Message-ID: <87ef302r8f.fsf@mouse.gnus.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see @@CONTACT_ADDRESS@@ for details. Content preview: Drew Adams writes: > Have the automatically provided part of a minor-mode doc string, from > `define-minor-mode' do the following (or at least some of it): > > 1. Mention the mode variable (typically the same name as th [...] Content analysis details: (-2.9 points, 5.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0000] X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 36500 Cc: 36500@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) Drew Adams writes: > Have the automatically provided part of a minor-mode doc string, from > `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.) > > 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. Here's the current output from a random minor mode defined by that function: --- epa-mail-mode is an autoloaded interactive compiled Lisp function in =E2=80=98epa-mail.el=E2=80=99. (epa-mail-mode &optional ARG) A minor-mode for composing encrypted/clearsigned mails. If called interactively, enable epa-mail mode if ARG is positive, and disable it if ARG is zero or negative. If called from Lisp, also enable the mode if ARG is omitted or nil, and toggle it if ARG is =E2=80=98toggle=E2=80=99; disable the mode otherwise. --- No mention of a keymap? > 3. Say whether the variable is global (an option, customizable), or > buffer-local. Yes, that makes sense. Currently a number of these modes say so themselves, so that should also be adjusted: --- auto-insert-mode is an autoloaded interactive compiled Lisp function in =E2=80=98autoinsert.el=E2=80=99. (auto-insert-mode &optional ARG) Toggle Auto-insert mode, a global minor mode. [...] --- > 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/reset > it manually using Customize. Yup. > 5. Any particularities, e.g. from using `:variable' should be taken into > account, so the doc string is correct for all cases. Makes sense. --=20 (domestic pets only, the antidote for overdose, milk.) bloggy blog: http://lars.ingebrigtsen.no From debbugs-submit-bounces@debbugs.gnu.org Mon Jul 08 17:27:03 2019 Received: (at 36500) by debbugs.gnu.org; 8 Jul 2019 21:27:03 +0000 Received: from localhost ([127.0.0.1]:59734 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hkbA7-0006cz-CI for submit@debbugs.gnu.org; Mon, 08 Jul 2019 17:27:03 -0400 Received: from userp2130.oracle.com ([156.151.31.86]:47056) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hkbA5-0006cV-5S for 36500@debbugs.gnu.org; Mon, 08 Jul 2019 17:27:01 -0400 Received: from pps.filterd (userp2130.oracle.com [127.0.0.1]) by userp2130.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x68LNxon154390; Mon, 8 Jul 2019 21:26:55 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : cc : subject : references : in-reply-to : content-type : content-transfer-encoding; s=corp-2018-07-02; bh=fwaBrs4RSXWuOeN4fHzffeCYfI3MjqECkcgwrVyhCEE=; b=W2e4WZV+p8iBunZQu6+KwDhPN653BzxKQkTLknd4qwpcIrc+j05+UvlCGefImBCpzgRL pVme2olgJopro/XcTjYkJyh73CQWLvBa5TWV7UxGGsVV/Z6DDqJ+f5YqTK3bL/ChYHMJ WqVU0xZGYvazVWIxKEUpwD7c1dLw5X32Vz1d1iVmFLkSw9TIRSFNlqkNdspgK7CwjlO5 91a1dUFFIJdgWrCoq7WSC3ZOqutSVzELwB96bqiY0BShJ2tMZs044GX/YlaRLjUHpaQg ZKwGf0a9UM/yDufF+8o0gs89COlgD3g8LceH/hb73HnICcxO/BrxlhwPF9/A+ZsFSh/W 7Q== Received: from userp3020.oracle.com (userp3020.oracle.com [156.151.31.79]) by userp2130.oracle.com with ESMTP id 2tjk2tgu9d-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Mon, 08 Jul 2019 21:26:54 +0000 Received: from pps.filterd (userp3020.oracle.com [127.0.0.1]) by userp3020.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x68LNIdr013041; Mon, 8 Jul 2019 21:26:54 GMT Received: from userv0122.oracle.com (userv0122.oracle.com [156.151.31.75]) by userp3020.oracle.com with ESMTP id 2tjjyke7jf-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Mon, 08 Jul 2019 21:26:54 +0000 Received: from abhmp0009.oracle.com (abhmp0009.oracle.com [141.146.116.15]) by userv0122.oracle.com (8.14.4/8.14.4) with ESMTP id x68LQrf2008267; Mon, 8 Jul 2019 21:26:53 GMT MIME-Version: 1.0 Message-ID: <33fe31aa-ffe3-485d-bdf6-37f371877c2f@default> Date: Mon, 8 Jul 2019 14:26:52 -0700 (PDT) From: Drew Adams To: Lars Ingebrigtsen Subject: RE: bug#36500: 26.2; Minor mode doc strings - say what the current mode-variable value is References: <4dc6d6ce-351c-426a-8371-3ce170c74f1a@default> <87ef302r8f.fsf@mouse.gnus.org> In-Reply-To: <87ef302r8f.fsf@mouse.gnus.org> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4861.0 (x86)] Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9312 signatures=668688 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=0 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1907080267 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9312 signatures=668688 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 priorityscore=1501 malwarescore=0 suspectscore=0 phishscore=0 bulkscore=0 spamscore=0 clxscore=1011 lowpriorityscore=0 mlxscore=0 impostorscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1907080267 X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 36500 Cc: 36500@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > > Have the automatically provided part of a minor-mode doc string, from > > `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.) > > > > 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 > Here's the current output from a random minor mode defined by that > function:... > No mention of a keymap? Sorry, but I don't recall which minor-mode help I was looking at the day I filed that bug (shoulda noted the function name). But the mode was defined by `define-minor-mode', and the help had a sentence saying that (minor-map) keymap such-and-such was not yet defined. The map variable was mentioned and its value was described, at least that far. In any case, #1 and #2 here are about the mode variable, not the keymap variable. > > 3. Say whether the variable is global (an option, customizable), or > > buffer-local. >=20 > Yes, that makes sense. Currently a number of these modes say so > themselves, so that should also be adjusted: Right. Many mode doc strings provide info that is not provided, or was not provided at one point, by `define-minor-mode'. From debbugs-submit-bounces@debbugs.gnu.org Tue Jun 22 10:07:16 2021 Received: (at 36500) by debbugs.gnu.org; 22 Jun 2021 14:07:16 +0000 Received: from localhost ([127.0.0.1]:39574 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lvh3c-0001mI-6F for submit@debbugs.gnu.org; Tue, 22 Jun 2021 10:07:16 -0400 Received: from quimby.gnus.org ([95.216.78.240]:37080) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lvh3a-0001m1-Tg for 36500@debbugs.gnu.org; Tue, 22 Jun 2021 10:07:15 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnus.org; s=20200322; h=Content-Type:MIME-Version:Message-ID:In-Reply-To:Date: References:Subject:Cc:To:From:Sender:Reply-To:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=BIX5Lx27A+dNyFMGqpie54exU3JyoPo6HxkN/Ih+qKo=; b=WrhUyLmdDaLuEL6kYIpLI8Y0lI dgpOZ+UAH+RLUm3xr6aUj9bqmMOuCEWrDNDnrg0fk9Dw3w/eRAe8n80l/8Msi2+tpDjtH8Q8tzHEh wLGWoTGS99L2y37WOsHAyshqcN9h9JeWOA4H5bQTZbUXOHqacAKm9K+2X3cCjaTud5O8=; Received: from cm-84.212.220.105.getinternet.no ([84.212.220.105] helo=elva) by quimby.gnus.org with esmtpsa (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1lvh3O-0007OI-5A; Tue, 22 Jun 2021 16:07:04 +0200 From: Lars Ingebrigtsen To: Drew Adams Subject: Re: bug#36500: 26.2; Minor mode doc strings - say what the current mode-variable value is References: <4dc6d6ce-351c-426a-8371-3ce170c74f1a@default> X-Now-Playing: Talking Heads's _Fear of Music_: "Memories Can't Wait" Date: Tue, 22 Jun 2021 16:07:01 +0200 In-Reply-To: <4dc6d6ce-351c-426a-8371-3ce170c74f1a@default> (Drew Adams's message of "Thu, 4 Jul 2019 08:19:36 -0700 (PDT)") Message-ID: <87k0mmouwq.fsf@gnus.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see @@CONTACT_ADDRESS@@ for details. Content preview: Drew Adams writes: > `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'). > ( [...] Content analysis details: (-2.9 points, 5.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0000] X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 36500 Cc: 36500@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Drew Adams writes: > `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.) I've now done this in Emacs 28. > 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. 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. > 3. Say whether the variable is global (an option, customizable), or > buffer-local. For minor modes? No, I think that would be counter-productive -- minor modes should be toggled with the minor mode command. And besides -- the "mode variable" isn't necessarily a variable: You can use a general setf-able thing for it. And the getter and the setter aren't the same. The useful thing, I think, is to have the doc string document the getter "variable", so that you know how to check whether the mode is off or on. (Which I've now done, so I'm closing this bug report.) > 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/reset > it manually using Customize. Ditto. -- (domestic pets only, the antidote for overdose, milk.) bloggy blog: http://lars.ingebrigtsen.no From debbugs-submit-bounces@debbugs.gnu.org Tue Jun 22 10:07:19 2021 Received: (at control) by debbugs.gnu.org; 22 Jun 2021 14:07:19 +0000 Received: from localhost ([127.0.0.1]:39576 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lvh3f-0001mX-GS for submit@debbugs.gnu.org; Tue, 22 Jun 2021 10:07:19 -0400 Received: from quimby.gnus.org ([95.216.78.240]:37094) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lvh3a-0001m6-Tg for control@debbugs.gnu.org; Tue, 22 Jun 2021 10:07:16 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnus.org; s=20200322; h=Subject:From:To:Message-Id:Date:Sender:Reply-To:Cc: MIME-Version:Content-Type:Content-Transfer-Encoding:Content-ID: Content-Description:Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc :Resent-Message-ID:In-Reply-To:References:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=atWqpujXF+RCGd/sO9oXSuXh543yVpfJPIw749wGKHU=; b=reMsaDobA3tgImn5nxpYouh+S5 007dIywqXySvmVjxAZZQcvhB9GUmVNq7dQ2wZt0scGHfeLKelUYTZWx074v6EUaQZ0nLlWGdA3+l0 3EuGuCDsOf/IHNE+37bh4rMNdaiqfTTFtjnMkmvIDQRW7eh/5OASkdteLXk784PFF/zo=; Received: from cm-84.212.220.105.getinternet.no ([84.212.220.105] helo=elva) by quimby.gnus.org with esmtpsa (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1lvh3S-0007OR-NP for control@debbugs.gnu.org; Tue, 22 Jun 2021 16:07:08 +0200 Date: Tue, 22 Jun 2021 16:07:06 +0200 Message-Id: <87im26ouwl.fsf@gnus.org> To: control@debbugs.gnu.org From: Lars Ingebrigtsen Subject: control message for bug #36500 X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see @@CONTACT_ADDRESS@@ for details. Content preview: close 36500 28.1 quit Content analysis details: (-2.9 points, 5.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0000] X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) close 36500 28.1 quit From debbugs-submit-bounces@debbugs.gnu.org Tue Jun 22 11:10:11 2021 Received: (at 36500) by debbugs.gnu.org; 22 Jun 2021 15:10:11 +0000 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 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 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== 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 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 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= 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 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 From: Drew Adams To: Lars Ingebrigtsen Subject: RE: [External] : Re: bug#36500: 26.2; Minor mode doc strings - say what the current mode-variable value is 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 Date: Tue, 22 Jun 2021 15:10:03 +0000 Message-ID: References: <4dc6d6ce-351c-426a-8371-3ce170c74f1a@default> <87k0mmouwq.fsf@gnus.org> In-Reply-To: <87k0mmouwq.fsf@gnus.org> Accept-Language: en-US Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: 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: =?us-ascii?Q?zDl/Mh/wfmLaLUuLxStImQA2BoUT+bpyygeKJ0q0rAEkZ3mcSZBwT2uGPiOj?= =?us-ascii?Q?cwu3A1Y8G1+0yOkTxSXILG7+zP9RqLRXFgFM7jb7iHC1IPWBAYZM3eoaMe3o?= =?us-ascii?Q?t3g/+pEL6nCYOeW2eIw6of+Q7CQpSaDNCo3kl5OR1RjL0D7mG8knXdu++8vh?= =?us-ascii?Q?jCjwMaX/esRI81Pd+C7AYXkI3MuSeU/x48sw/z8uR4/P7bSSwtIVNvHGS/Ob?= =?us-ascii?Q?ljcVBGxT41rc6LkKWi2T6Vs/SHrPrwbsaqsCxbAJC0rCIK4JAPOb4Dw2jVc7?= =?us-ascii?Q?7BE6mR2/XA0CR46pYlWLEGqMtvnnNjrVMO1gq+9k/QTet6bmhDjcdM5SZWh/?= =?us-ascii?Q?amTm16B3IODXWBCFqAVdkSM3oFT3v8LmB1EbFw4FvjaPLh1+dSWQ4nGBlYYs?= =?us-ascii?Q?PPwZ0KFn1gyfIZyXUdF0NKTvD9+lSiEPZCS3tyIraLbugrZmiBg97FICwRCY?= =?us-ascii?Q?CPZOql/yFV9UPGnm08RwT0yWQahanJjZ0ClNYJCUDO6Uha5m3LVy9/2GlEFZ?= =?us-ascii?Q?QPvmT4/T1SxuPVXPtQ34mVym88jJA1RZQ+6Em6KIRtj4so5/Zr9NSJggEG8i?= =?us-ascii?Q?Cx4zEpErHKx3xXUkNIh9sHU6V7NFugnJIvp5klsxrC+KY7t0LEhFlQupmVP8?= =?us-ascii?Q?LvrwC918FQC83MaocpvaILy9UlSwrdULn2I6D/K8GPAu3Y3QgEpjbcIY6ASW?= =?us-ascii?Q?A239AA0Koai8rXZSUChHqOaGur9wpOhvZYPKMFfDU8dugSXFCZKjTVhjqM3F?= =?us-ascii?Q?GMPDdy5DzP9rgvFw46Hx0o5Kpz4cJtXBtjq+0snAe4Qps7Ma+ZmYA2lxzRzT?= =?us-ascii?Q?5TxzI2k48pxXS1C+hO2UUELnFmPt90OzJ2inYziMw77EIXJCFieTla7Jm8Yr?= =?us-ascii?Q?IsNRaWai2voMIqvhUb6FuyHjEbHQ31lykeOuvx+2bzD8XGm+iaEwzKYmk+9L?= =?us-ascii?Q?+Ow0U7V99ARGk72YQatYffmt/s2MZZyAA0cMOIcS8U63RmyMzxo/YY0TXWCj?= =?us-ascii?Q?/pVPBbZBT4wsAZN06qC8i4O9HgePrL25pWZURHekYFm9TCB0Or9abXlAkSjt?= =?us-ascii?Q?lC3O/YRtqH+5Nk2hrH0yRTVdJwogHonOaW7MCkiOPcxZKjI3kCRO6oNDohDb?= =?us-ascii?Q?a8xWXbde1+yGo9Ib7yB9bQ/Hl3tlq7pDKlA//M8iEMJGK85x1CvJ8J4V4Cqz?= =?us-ascii?Q?4iIemvaMPBZJcUHiWVOr6zpdRSTgM81aql4fH+TKXELAgM2tmwlpq2isPjvg?= =?us-ascii?Q?40jPCENqWsA2DRDpTQTqYSuungQYxoSUzeqgOlGfAEM5GDz3CFezY2LvIwxD?= =?us-ascii?Q?swk=3D?= x-ms-exchange-transport-forked: True Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 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-Spam-Score: -0.7 (/) X-Debbugs-Envelope-To: 36500 Cc: "36500@debbugs.gnu.org" <36500@debbugs.gnu.org> X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.7 (-) > > `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). From unknown Fri Aug 15 16:18:57 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Wed, 21 Jul 2021 11:24:04 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator