From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Lars Ingebrigtsen Newsgroups: gmane.emacs.bugs Subject: bug#36500: 26.2; Minor mode doc strings - say what the current mode-variable value is Date: Tue, 22 Jun 2021 16:07:01 +0200 Message-ID: <87k0mmouwq.fsf@gnus.org> References: <4dc6d6ce-351c-426a-8371-3ce170c74f1a@default> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="11840"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) Cc: 36500@debbugs.gnu.org To: Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Tue Jun 22 16:08:11 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 1lvh4U-0002vk-6j for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 22 Jun 2021 16:08:10 +0200 Original-Received: from localhost ([::1]:42926 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1lvh4T-0001sn-5Z for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 22 Jun 2021 10:08:09 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:34588) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lvh4M-0001sW-Sq for bug-gnu-emacs@gnu.org; Tue, 22 Jun 2021 10:08:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:56263) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1lvh4M-00088N-Lp for bug-gnu-emacs@gnu.org; Tue, 22 Jun 2021 10:08:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1lvh4M-0001nZ-IW for bug-gnu-emacs@gnu.org; Tue, 22 Jun 2021 10:08:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Lars Ingebrigtsen Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 22 Jun 2021 14:08:02 +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.16243708366848 (code B ref 36500); Tue, 22 Jun 2021 14:08:02 +0000 Original-Received: (at 36500) by debbugs.gnu.org; 22 Jun 2021 14:07:16 +0000 Original-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 Original-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=; Original-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 X-Now-Playing: Talking Heads's _Fear of Music_: "Memories Can't Wait" In-Reply-To: <4dc6d6ce-351c-426a-8371-3ce170c74f1a@default> (Drew Adams's message of "Thu, 4 Jul 2019 08:19:36 -0700 (PDT)") 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:208862 Archived-At: 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