From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Stefan Monnier Newsgroups: gmane.emacs.devel Subject: Re: doc on define-minor-mode hook variable(s) Date: Sun, 05 Mar 2006 18:33:18 -0500 Message-ID: <87veusmqa9.fsf-monnier+emacs@gnu.org> References: NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: sea.gmane.org 1141601646 2574 80.91.229.2 (5 Mar 2006 23:34:06 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sun, 5 Mar 2006 23:34:06 +0000 (UTC) Cc: Emacs-Devel Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Mar 06 00:34:03 2006 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1FG2jL-0001Na-3G for ged-emacs-devel@m.gmane.org; Mon, 06 Mar 2006 00:33:39 +0100 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1FG2jT-0003rA-1E for ged-emacs-devel@m.gmane.org; Sun, 05 Mar 2006 18:33:47 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1FG2jE-0003AB-EF for emacs-devel@gnu.org; Sun, 05 Mar 2006 18:33:32 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1FG2jB-0002hJ-0t for emacs-devel@gnu.org; Sun, 05 Mar 2006 18:33:32 -0500 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1FG2jA-0002gW-Sj for emacs-devel@gnu.org; Sun, 05 Mar 2006 18:33:28 -0500 Original-Received: from [209.226.175.25] (helo=tomts5-srv.bellnexxia.net) by monty-python.gnu.org with esmtp (Exim 4.52) id 1FG2lI-0002R8-EA for emacs-devel@gnu.org; Sun, 05 Mar 2006 18:35:40 -0500 Original-Received: from alfajor ([70.48.80.201]) by tomts5-srv.bellnexxia.net (InterMail vM.5.01.06.13 201-253-122-130-113-20050324) with ESMTP id <20060305233319.EIBB18394.tomts5-srv.bellnexxia.net@alfajor>; Sun, 5 Mar 2006 18:33:19 -0500 Original-Received: by alfajor (Postfix, from userid 1000) id CA0B8D73BB; Sun, 5 Mar 2006 18:33:18 -0500 (EST) Original-To: "Drew Adams" In-Reply-To: (Drew Adams's message of "Sun, 5 Mar 2006 13:14:50 -0800") User-Agent: Gnus/5.11 (Gnus v5.11) Emacs/22.0.50 (gnu/linux) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:51252 Archived-At: > OK, thanks for the clarification. > I don't see how that substantially alters my point (or even most of what I > wrote): more should be said about the hook _symbol_ `MODE-hook' in the doc. > Users should be informed how they can take advantage of this feature. The main point I saw was: > > That seems clear: there is a hook and it is run at the end of entering > > and exiting the mode. What's not clear from this doc is whether > > `define-minor-mode' creates a variable named `MODE-hook'. And my explanation says that the part that's not clear is related to hooks in general, not to define-minor-mode's hooks in particular. > My concern is not really whether or not these hooks exist. My concern is > that they are provided for by `define-minor-mode' but the behavior related > to them is not sufficiently documented. IOW, important functionality > provided by `define-minor-mode' is not revealed by the doc. Like what? Other comment on your previous message: > > The code defining `define-minor-mode' does bind hook variables > > `MODE-hook', `MODE-on-hook', and `MODE-off-hook'. A comment explains > > that `*-on-*' and `*-off-*' are only for backward compatibility. > > The function created by the macro runs these hooks not at its end, but > > before the minor-mode keymap is defined and the minor mode is added to > > minor-mode-alist - but that's a detail. It is not true that those hooks are run "before the minor-mode keymap is defined and the minor mode is added to minor-mode-alist". Both of those actions are done at the top-level when the minor-mode function is defined rather than when it's called, so they should both happen before the hook is run (even though they indeed appear afterwards in the code). > > - no hook vars are created by `define-minor-mode' 3 hooks are defined (the concept of a "hook var" should be avoided since it's misleading). You can manipulate them with `add-hook' and `remove-hook' like all other hooks and they are run with `run-hooks'. > > - if you create them, they should be named `MODE-hook', `MODE-on-hook', > > and `MODE-off-hook' (or perhaps we should not mention the latter two?) *You* don't create them. They exist already. And yes, mone-on-hook and mode-off-hook should not be mentioned. > > - if defined, the hooks are run near the end of the minor-mode function, > > just before the minor-mode map is defined They're run just like major mode hooks: at the end of the minor mode function. > > The doc for `define-minor-mode' could also remind people that it is > > sufficient to use `(add-hook 'MODE-hook...)' to define such a hook. add-hook modifies it: it doesn't define it. And saying "it's sufficient to use add-hook" is misleading: add-hook is the *only* way to manipulate hooks. `add-to-list' and `setq' are *wrong*. Stefan