From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: =?utf-8?Q?K=C3=A9vin_Le_Gouguec?= Newsgroups: gmane.emacs.help Subject: Re: Enabling a globalized-minor-mode by default Date: Sat, 12 Sep 2020 12:01:47 +0200 Message-ID: <87pn6rl3ec.fsf@gmail.com> References: <87pn6tmoti.fsf@gmail.com> <87ft7olm6c.fsf@gmail.com> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="15890"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) Cc: help-gnu-emacs@gnu.org To: Stefan Monnier Original-X-From: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane-mx.org@gnu.org Sat Sep 12 12:02:17 2020 Return-path: Envelope-to: geh-help-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 1kH2MK-0003zh-0W for geh-help-gnu-emacs@m.gmane-mx.org; Sat, 12 Sep 2020 12:02:16 +0200 Original-Received: from localhost ([::1]:40278 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kH2MJ-0005yT-10 for geh-help-gnu-emacs@m.gmane-mx.org; Sat, 12 Sep 2020 06:02:15 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:59698) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kH2Ly-0005yE-Tz for help-gnu-emacs@gnu.org; Sat, 12 Sep 2020 06:01:54 -0400 Original-Received: from mail-wr1-x435.google.com ([2a00:1450:4864:20::435]:39211) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kH2Lw-0004I7-PO for help-gnu-emacs@gnu.org; Sat, 12 Sep 2020 06:01:54 -0400 Original-Received: by mail-wr1-x435.google.com with SMTP id a17so13759218wrn.6 for ; Sat, 12 Sep 2020 03:01:51 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version:content-transfer-encoding; bh=O8l8sERcfRHOJG3/z/jdgpfdfEYYASOL1h104Jp5uKg=; b=WQaXLk5f88F/jMgnxHD+aYliRFpJmgKSi77mGTjkbmW63GHNSIQN5HqXrS5NJ0b5UA 9Ge87Qp4CAjp+ZpIwdJDbvMw108sqhmT6ZhC83vzAoEbzYJg+mEDsTjh9mFfjjEl+KtI zl5FPPbQRLMwFjuQCfCKeRp10suU1p+dbe7gxZVE2wTFguJUO0xP6lzVsYDVNHfarwnN N+vaMS5vJFqOzKMGUpH+gNAPxEsdZ37Yp8sYxUtH9I4EUq2Kqso7HwXjqOj+MsMvcrjT C7NBFWAT8LJFGcfVghCtpHs6oZW8V2OijK4Q9beOjIRawNrW3c9Q+jgr0i5sswBSVVNE xk6g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:references:date:in-reply-to :message-id:user-agent:mime-version:content-transfer-encoding; bh=O8l8sERcfRHOJG3/z/jdgpfdfEYYASOL1h104Jp5uKg=; b=V9Otw0b0LMDwO0yV2g9IEP+ayJeXoDVEUx9kwEZXFez8yit1UGdTqEFC3KUCRDt/wq Zeo1yzvKFt1fgE9sWhT2fsoXIkzA+B1zn2lAhlf93RXue8E1PJU2WkevvnDFOOvTk3aD fj+BWY/18c5aSV0CvhUtmfGVm+zT3ypO9upotEvTQ5DqdIes/gQthyCvixcx8/UU1iIa oX6BX507qiXikoe/mXnGcoFW5TKUIxS5ei/Nrbrx2Tp57ju55th9AGCQTN774qN+xgjl 0nLtJZbl349bnsWt6h4u6DjK/SShQONkVGF4fDUp7jXKPL16zUqb3A8tSdHZA3RdTQxf c3nQ== X-Gm-Message-State: AOAM531zgEB6Zd+BDPgOfj8BXjhEgIc+8w/MnA71Sh05y40mmwIoh6b5 7pkROOQWlBI1Imv5VSU9YJuTvsyLFdQ= X-Google-Smtp-Source: ABdhPJwtow3hf4HV43+VBzo+kpPcZkQViV4aXciSXlCYQpHzEp1+Y5x7DPhz8Jdu03IDfdt3vPBtWQ== X-Received: by 2002:adf:efc9:: with SMTP id i9mr6437605wrp.187.1599904909517; Sat, 12 Sep 2020 03:01:49 -0700 (PDT) Original-Received: from hirondell ([2a01:e0a:20e:d340:41b7:7b2e:4aab:4832]) by smtp.gmail.com with ESMTPSA id i6sm10713968wra.1.2020.09.12.03.01.48 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 12 Sep 2020 03:01:48 -0700 (PDT) In-Reply-To: (Stefan Monnier's message of "Fri, 11 Sep 2020 11:03:10 -0400") Received-SPF: pass client-ip=2a00:1450:4864:20::435; envelope-from=kevin.legouguec@gmail.com; helo=mail-wr1-x435.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: help-gnu-emacs@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: Users list for the GNU Emacs text editor List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "help-gnu-emacs" Xref: news.gmane.io gmane.emacs.help:124031 Archived-At: Stefan Monnier writes: > I guess the docstring is so long already that adding a couple more lines > couldn't hurt, but really it's just a general principle, not specific to > minor modes. Fair enough. I don't know how people come to write minor modes (I was just trying to "fix" one). Maybe most of them are diligent enough to read the manual first? I'd bet that a few lost souls will just read define-minor-mode's docstring and go from there, and won't necessarily be acquainted with this general principle. For better or worse, Emacs's docstrings look fairly comprehensive, so it's tempting to assume they cover everything one needs to know. I, for one, have yet to acquire the reflex to dig up the manual when something doesn't match the expectations I got from the docstring. It's not that C-h S is harder to hit than C-h f, but if nothing in the docstring hints at things being More Complicated Than They Look=E2=84=A2, it won't occur to me to reach for the manual. > Would the patch below help? > > diff --git a/lisp/emacs-lisp/easy-mmode.el b/lisp/emacs-lisp/easy-mmo= de.el > index e3eb9294ed..1cde808e7a 100644 > --- a/lisp/emacs-lisp/easy-mmode.el > +++ b/lisp/emacs-lisp/easy-mmode.el > @@ -137,6 +137,10 @@ define-minor-mode > usage of the mode argument. >=20=20=20=20=20=20 > Optional INIT-VALUE is the initial value of the mode's variable. > + Note that the minor mode function won't be called by setting > + this option, so the value *reflects* the minor mode's natural > + initial state, rather than *setting* it. > + In the vast majority of cases it should be nil. > Optional LIGHTER is displayed in the mode line when the mode is on. > Optional KEYMAP is the default keymap bound to the mode keymap. > If non-nil, it should be a variable name (whose value is a keymap), I think it does. AFAICT the current description does nothing to warn the user that there are two sources of truth (the mode variable, and calling the mode function). IMO it's easy to assume that INIT-VALUE controls activation: what would be the point of letting the user set the variable without calling the mode function? The added lines hint that activation is more or less independent of INIT-VALUE; I think it's enough to prompt the user to go fish for more documentation. Thank you for coming up with these! PS: while trying to assess how common the ":init-value t enables the mode" fallacy is (if at all), I found this thread: https://old.reddit.com/r/emacs/comments/aw84yn/defineminormode_initvalu= e_t_not_running_its_hook/ This smonnier person sure sounds like a knowledgeable fellow :D and look at /u/tarsius_, with this helpful example code!