bug#6218: 23.2; Hooks doc needs improvement about running local & global

["Drew Adams" <drew.adams@oracle.com>]

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'