bug#25794: 24.5; Doc of `Info-selection-hook'

bug#25794: 24.5; Doc of `Info-selection-hook'

[Drew Adams]

This is a hook: a variable used by users to automatically invoke
functions when something happens.

Sure, it's true that "when something happens" means, more precisely, at
certain places in the implementation (code).  But a hook is a user-level
thing, and hooks should be, first of all, presented to users as such.
Their descriptions should make clear to users when they are used.

That's not really the case for `Info-selection-hook', IMO.  Why?
Because users do not know what "when `Info-select-node' is called"
means.  They know nothing about non-interactive function
`Info-select-node'.

(Also, the doc string says "Hooks run" - that should be singular.)

`Info-select-node' is an implementation detail.  It is not at all clear
to users when that function gets called.  The doc for the hook should,
first of all, say when the hook is run in terms of user-observable and
user-understandable behavior.  It is fine to ALSO then say something
like "More precisely, the hook is run when `Info-select-node' is called."
That can perhaps help users who consult the code to know better what the
behavior is.

In user-level terms, when is this hook run?  Perhaps just say that it is
run whenever an Info node (or page) is visited.  Yes, it applies also to
reversion and other revisits of a node, and it applies also to visiting
a TOC, which is not really a node.  Still, visiting a node is the best
thing I can think of that describes the behavior to users.  Perhaps you
have a better idea?

I think, too, that it would be OK to say that the hook runs _after_ a
node is visited or near the end of visiting a node.

But please say something that is more helpful than just "Hooks run when
`Info-select-node' is called."


In GNU Emacs 24.5.1 (i686-pc-mingw32)
 of 2015-04-11 on LEG570
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/usr --host=i686-pc-mingw32'

bug#25794: 24.5; Doc of `Info-selection-hook'

[Eli Zaretskii]

> Date: Sun, 19 Feb 2017 09:28:27 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> 
> This is a hook: a variable used by users to automatically invoke
> functions when something happens.
> 
> Sure, it's true that "when something happens" means, more precisely, at
> certain places in the implementation (code).  But a hook is a user-level
> thing, and hooks should be, first of all, presented to users as such.
> Their descriptions should make clear to users when they are used.
> 
> That's not really the case for `Info-selection-hook', IMO.  Why?
> Because users do not know what "when `Info-select-node' is called"
> means.  They know nothing about non-interactive function
> `Info-select-node'.
> 
> (Also, the doc string says "Hooks run" - that should be singular.)

Fixed on the emacs-25 branch.

Thanks.