From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.bugs Subject: bug#6218: 23.2; Hooks doc needs improvement about running local & global Date: Tue, 18 May 2010 13:52:44 -0700 Message-ID: <8ADE13315E8340F6907A4A4115DC857B@us.oracle.com> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: dough.gmane.org 1274219827 26241 80.91.229.12 (18 May 2010 21:57:07 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Tue, 18 May 2010 21:57:07 +0000 (UTC) To: 6218@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue May 18 23:57:06 2010 connect(): No such file or directory Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1OEUmf-0005lD-7c for geb-bug-gnu-emacs@m.gmane.org; Tue, 18 May 2010 23:57:05 +0200 Original-Received: from localhost ([127.0.0.1]:41665 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OEUme-0002lS-Ny for geb-bug-gnu-emacs@m.gmane.org; Tue, 18 May 2010 17:57:04 -0400 Original-Received: from [140.186.70.92] (port=40340 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OEUmZ-0002l0-CL for bug-gnu-emacs@gnu.org; Tue, 18 May 2010 17:57:00 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OEUmW-0008BF-9y for bug-gnu-emacs@gnu.org; Tue, 18 May 2010 17:56:59 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:48114) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OEUmV-0008B3-GL for bug-gnu-emacs@gnu.org; Tue, 18 May 2010 17:56:56 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1OEUgo-00048l-50; Tue, 18 May 2010 17:51:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 18 May 2010 21:51:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 6218 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: X-Debbugs-Original-To: Original-Received: via spool by submit@debbugs.gnu.org id=B.127421940415905 (code B ref -1); Tue, 18 May 2010 21:51:01 +0000 Original-Received: (at submit) by debbugs.gnu.org; 18 May 2010 21:50:04 +0000 Original-Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OEUfs-00048T-9I for submit@debbugs.gnu.org; Tue, 18 May 2010 17:50:04 -0400 Original-Received: from mx10.gnu.org ([199.232.76.166]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OEUfp-000483-U9 for submit@debbugs.gnu.org; Tue, 18 May 2010 17:50:02 -0400 Original-Received: from lists.gnu.org ([199.232.76.165]:41504) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1OEUfm-0008FG-1w for submit@debbugs.gnu.org; Tue, 18 May 2010 17:49:58 -0400 Original-Received: from [140.186.70.92] (port=38779 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OEUfk-0008LK-OC for bug-gnu-emacs@gnu.org; Tue, 18 May 2010 17:49:57 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OETnD-0007YB-AQ for bug-gnu-emacs@gnu.org; Tue, 18 May 2010 16:53:37 -0400 Original-Received: from rcsinet10.oracle.com ([148.87.113.121]:38755) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OETnD-0007Xv-3O for bug-gnu-emacs@gnu.org; Tue, 18 May 2010 16:53:35 -0400 Original-Received: from rcsinet13.oracle.com (rcsinet13.oracle.com [148.87.113.125]) by rcsinet10.oracle.com (Switch-3.4.2/Switch-3.4.1) with ESMTP id o4IKrUvL023634 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Tue, 18 May 2010 20:53:32 GMT Original-Received: from acsmt354.oracle.com (acsmt354.oracle.com [141.146.40.154]) by rcsinet13.oracle.com (Switch-3.4.2/Switch-3.4.1) with ESMTP id o4IJCJnf029761 for ; Tue, 18 May 2010 20:53:28 GMT Original-Received: from abhmt014.oracle.com by acsmt354.oracle.com with ESMTP id 278042791274215960; Tue, 18 May 2010 13:52:40 -0700 Original-Received: from dradamslap1 (/141.144.80.23) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Tue, 18 May 2010 13:52:40 -0700 X-Mailer: Microsoft Office Outlook 11 Thread-Index: Acr2zBA98KHPm2fzSXSZ30gd/gOXcw== X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5931 X-Auth-Type: Internal IP X-Source-IP: rcsinet13.oracle.com [148.87.113.125] X-CT-RefId: str=0001.0A090202.4BF2FE4C.013D:SCFMA4539811,ss=1,fgs=0 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-detected-operating-system: by monty-python.gnu.org: GNU/Linux 2.6, seldom 2.4 (older, 4) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Tue, 18 May 2010 17:51:02 -0400 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) 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: , Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:37027 Archived-At: Maybe it's there and I just can't seem to find it, but it seems to me that the doc about running hooks should describe what happens when there are local and global versions of a hook - e.g. for `post-command-hook. The logical place for that explanation is node (elisp) Running Hooks. The only place I see it mentioned is in node Setting Hooks, where the LOCAL optional arg to `add-hook' is described. And the explanation there is vague and incomplete. For example: "If needed, this makes the hook buffer-local and adds `t' to the buffer-local value. The latter acts as a flag to run the hook functions in the default value as well as in the local value." What does "if needed" mean here? When is it needed? And what is the scope of that phrase? Normal English would suggest that it applies to the rest of the sentence, hence both to making the hook buffer-local and to adding `t' to the value. Under what circumstances will both the local and default values be run? Always (is `t' always present)? And just how is `t' added to the buffer-local value? At the end? There is in fact *NO* explanation of what it even means to have `t' as a member of a hook value. Node `Hooks' says clearly that the hook functions must be valid functions, which excludes `t'. I see no mention of `t' as a possible entry, and the entire discussion of hooks talks about invoking each of the entries as a function. In sum, this is as clear as mud. There should be a clear explanation of what happens when there are both local and global values. And it should be clear about just what happens if LOCAL is non-nil: is t added always, so that the default value is also processed? In GNU Emacs 23.2.1 (i386-mingw-nt5.1.2600) of 2010-05-08 on G41R2F1 Windowing system distributor `Microsoft Corp.', version 5.1.2600 configured using `configure --with-gcc (3.4) --no-opt --cflags -Ic:/xpm/include'