GNU bug report logs - #6218
23.2; Hooks doc needs improvement about running local & global

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 6218 in the body.
You can then email your comments to 6218 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 23.2; Hooks doc needs improvement about running local & global
Date: Tue, 18 May 2010 13:52:44 -0700

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'
 

Message #8 received at 6218 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 6218 <at> debbugs.gnu.org
Subject: Re: bug#6218: 23.2;
	Hooks doc needs improvement about running local & global
Date: Tue, 18 May 2010 21:57:54 -0400

> What does "if needed" mean here?  When is it needed?  And what is the

Indeed it shouldn't be there: it's an implementation detail.


        Stefan

Message #15 received at 6218 <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 6218 <at> debbugs.gnu.org
Subject: Re: 23.2; Hooks doc needs improvement about running local & global
Date: Wed, 13 Jul 2011 23:43:43 +0200

"Drew Adams" <drew.adams <at> oracle.com> writes:

> 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.

I've now added some text about buffer-local hooks to that node, and to
the Emacs manual.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Message #18 received at 6218 <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 6218 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#6218: 23.2;
	Hooks doc needs improvement about running local & global
Date: Wed, 13 Jul 2011 23:33:18 +0200

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

>> What does "if needed" mean here?  When is it needed?  And what is the
>
> Indeed it shouldn't be there: it's an implementation detail.

I've now removed the "if needed".

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Message #21 received at 6218 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Lars Magne Ingebrigtsen'" <larsi <at> gnus.org>,
	"'Stefan Monnier'" <monnier <at> iro.umontreal.ca>
Cc: 6218 <at> debbugs.gnu.org
Subject: RE: bug#6218: 23.2;
	Hooks doc needs improvement about running local & global
Date: Wed, 13 Jul 2011 15:12:21 -0700

> >> What does "if needed" mean here?  When is it needed?  And 
> >> what is the
> >
> > Indeed it shouldn't be there: it's an implementation detail.
> 
> I've now removed the "if needed".

That was one little piece of the bug report.
Why would you close this if that's the only part of it you fixed?

Message #26 received at 6218 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Lars Magne Ingebrigtsen'" <larsi <at> gnus.org>,
	"'Stefan Monnier'" <monnier <at> iro.umontreal.ca>
Cc: 6218 <at> debbugs.gnu.org
Subject: RE: bug#6218: 23.2;
	Hooks doc needs improvement about running local & global
Date: Wed, 13 Jul 2011 15:15:39 -0700

> That was one little piece of the bug report.
> Why would you close this if that's the only part of it you fixed?

OK, I just received your other message, where you speak about other parts of the
fix.

I'll close it again.  Thanks.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.