From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.devel Subject: doc on define-minor-mode hook variable(s) Date: Sun, 5 Mar 2006 11:40:14 -0800 Message-ID: NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: 7bit X-Trace: sea.gmane.org 1141587674 25510 80.91.229.2 (5 Mar 2006 19:41:14 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sun, 5 Mar 2006 19:41:14 +0000 (UTC) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Mar 05 20:41:12 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 1FFz69-0002Kl-J9 for ged-emacs-devel@m.gmane.org; Sun, 05 Mar 2006 20:40:57 +0100 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1FFz6G-0001JP-VS for ged-emacs-devel@m.gmane.org; Sun, 05 Mar 2006 14:41:05 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1FFz63-0000kp-25 for emacs-devel@gnu.org; Sun, 05 Mar 2006 14:40:51 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1FFz5z-0000Is-NF for emacs-devel@gnu.org; Sun, 05 Mar 2006 14:40:50 -0500 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1FFz5z-0000Io-K7 for emacs-devel@gnu.org; Sun, 05 Mar 2006 14:40:47 -0500 Original-Received: from [148.87.113.118] (helo=rgminet01.oracle.com) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_3DES_EDE_CBC_SHA:24) (Exim 4.52) id 1FFz85-0007I2-7d for emacs-devel@gnu.org; Sun, 05 Mar 2006 14:42:57 -0500 Original-Received: from rgmsgw301.us.oracle.com (rgmsgw301.us.oracle.com [138.1.186.50]) by rgminet01.oracle.com (Switch-3.1.6/Switch-3.1.6) with ESMTP id k25JeZf5011192 for ; Sun, 5 Mar 2006 12:40:35 -0700 Original-Received: from rgmsgw301.us.oracle.com (localhost [127.0.0.1]) by rgmsgw301.us.oracle.com (Switch-3.1.7/Switch-3.1.7) with ESMTP id k25JeZ5h027634 for ; Sun, 5 Mar 2006 12:40:35 -0700 Original-Received: from dradamslap (dhcp-amer-csvpn-gw1-141-144-64-199.vpn.oracle.com [141.144.64.199]) by rgmsgw301.us.oracle.com (Switch-3.1.7/Switch-3.1.7) with SMTP id k25JeX4e027626 (version=TLSv1/SSLv3 cipher=RC4-MD5 bits=128 verify=NO) for ; Sun, 5 Mar 2006 12:40:34 -0700 Original-To: "Emacs-Devel" X-Priority: 3 (Normal) X-MSMail-Priority: Normal X-Mailer: Microsoft Outlook IMO, Build 9.0.6604 (9.0.2911.0) Importance: Normal X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2800.1506 X-Brightmail-Tracker: AAAAAQAAAAI= X-Whitelist: TRUE 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:51239 Archived-At: Does `define-minor-mode' define a hook variable? If so, at what point is it run? These things are not documented clearly, IMO. There is only an oblique reference to a hook variable. The doc string of `define-minor-mode' says this: "body contains code that will be executed each time the mode is (dis)activated. It will be executed after any toggling but before running the hook variable `mode-HOOK'." (That should presumably be "MODE-hook", BTW, and "disactivate" should be "deactivate".) The Emacs-Lisp manual doc on `define-minor-mode' says this: "The command named MODE first performs the standard actions such as setting the variable named MODE and then executes the BODY forms, if any. It finishes by running the mode hook variable `MODE-hook'." 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'. I find no variable named `MODE-hook' in Emacs, where MODE is a minor mode name. Apparently, what is meant is that *if* someone creates a hook variable named `MODE-hook', then it will be run. 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. IIUC - No global hook vars are defined by `define-minor-mode'. If such variables happen to be defined, then their values are run as hooks. If this understanding is correct, then I think it should be reflected in the doc. The doc (string and manual) should say explicitly that: - no hook vars are created by `define-minor-mode' - 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?) - if defined, the hooks are run near the end of the minor-mode function, just before the minor-mode map is defined 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. Since such a hook is likely to be used by an end user (in .emacs), as well as by a programmer, perhaps it should also be mentioned in the Emacs manual, node Minor Modes or node Hooks. Node Hooks mentions major-mode hooks, but not minor-mode hooks.