From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.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: Mon, 08 Jul 2019 22:42:08 +0200 Message-ID: <87ef302r8f.fsf@mouse.gnus.org> References: <4dc6d6ce-351c-426a-8371-3ce170c74f1a@default> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="132384"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.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.org@gnu.org Mon Jul 08 22:59:12 2019 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1hkaj8-000XsK-K9 for geb-bug-gnu-emacs@m.gmane.org; Mon, 08 Jul 2019 22:59:10 +0200 Original-Received: from localhost ([::1]:44622 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.86_2) (envelope-from ) id 1hkaTw-0001SA-TP for geb-bug-gnu-emacs@m.gmane.org; Mon, 08 Jul 2019 16:43:29 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:54164) by lists.gnu.org with esmtp (Exim 4.86_2) (envelope-from ) id 1hkaTY-0001Rt-9b for bug-gnu-emacs@gnu.org; Mon, 08 Jul 2019 16:43:05 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hkaTW-0003uR-7q for bug-gnu-emacs@gnu.org; Mon, 08 Jul 2019 16:43:04 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:50865) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hkaTW-0003uM-3o for bug-gnu-emacs@gnu.org; Mon, 08 Jul 2019 16:43:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1hkaTV-0007bi-V3 for bug-gnu-emacs@gnu.org; Mon, 08 Jul 2019 16:43:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Lars Ingebrigtsen Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 08 Jul 2019 20:43: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.156261853429188 (code B ref 36500); Mon, 08 Jul 2019 20:43:01 +0000 Original-Received: (at 36500) by debbugs.gnu.org; 8 Jul 2019 20:42:14 +0000 Original-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 Original-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 Original-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 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-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 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.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:162364 Archived-At: 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