1) (elisp) `Advising Named Functions', 2) search filtering example

1) (elisp) `Advising Named Functions', 2) search filtering example

[Drew Adams]

1. Node `Advising Named Functions' of the Elisp manual says this:

 For these reasons, advice should be reserved for the cases
 where you cannot modify a function’s behavior in any other way.
 If it is possible to do the same thing via a hook, that is
 preferable. ...

 In particular, Emacs’s own source files should not put advice
 on functions in Emacs.  (There are currently a few exceptions
 to this convention, but we aim to correct them.)

Is that still true?  Is this the policy, even with the new
advice system?

If so, then it seems that it is being ignored, as new advice
has been added to `isearch-filter-predicate' in `dired-aux.el'
and `wdired.el'.

And the `isearch.el' code has been modified to accommodate such
advising, instead of, for example, just using a hook variable.

----

2. As a related aside, I recently added, to my library
`isearch+.el', an ability to add search-filter predicates on
the fly.

a. At first, I took the hook approach:

`isearch-filter-predicate' is essentially a hook, so I made
it one explicitly.  I modified (my version of) the code that
uses it, so that the value could be either a function or a
list of functions.  I used `run-hook-with-args-until-failure'
for the (now true) hook variable `isearch-filter-predicate'.

This approach was simple to implement.  However, it would
also mean modifying any and all code that uses or will use
`isearch-filter-predicate' differently.  In particular,
code in `replace.el', as well as the code in `dired-aux.el'
and `wdired.el' mentioned above.

b. Figuring that the current wave of advising instead of
hooking is here to stay, I then took the different approach
of using `add-function', `remove-function', etc. instead of
a hook.

The implementation is not as simple or straightforward as
for a hook, but it is clean enough.  I'm sticking with it,
as I expect that this is the way the wind is blowing now.

(Note that one difference from a hook is that a hook does
not privilege the first hook function in any way (or the
last, depending on how you look at it).  Removing advice
is not equivalent to `remove-hook'.  It never "empties the
hook" completely - the function that was advised is still
there after removal of all advice.)

Anyway, using either approach you can do any of these
things while searching, to modify the zones you search:

* `M-? &' (`isearchp-add-filter-predicate') adds a filter
  predicate, AND-ing it as an additional `:after-while' filter.

* `M-? |' (`isearchp-or-filter-predicate') adds a filter
  predicate, OR-ing it as an additional `:before-until' filter.

* `M-? ~' (`isearchp-complement-filter') complements the current
  filter.  It either adds an `:around' filter that complements
  or it removes an existing top-level complementing filter.

* `M-? -' (`isearchp-remove-filter-predicate') removes the last
  added filter predicate (aka advice).

* `M-? !' (`isearchp-set-filter-predicate') sets the overall
  filter predicate (advised `isearch-filter-predicate') to a
  single predicate.

* `M-? 0' (`isearchp-reset-filter-predicate') resets
  `isearch-filter-predicate' to its original (unadvised) value.

* `M-? s' (`isearchp-save-filter-predicate') saves the current
  filter-predicate suite (advised `isearch-filter-predicate')
  for subsequent searches.  Unless you save it, the next
  Isearch starts out from scratch, using the last (unadvised)
  value of `isearch-filter-predicate'.

* `M-? n' (`isearchp-defun-filter-predicate') names the current
  suite of filter predicates, creating a named predicate that
  does the same thing.  (You can use that name with `M-? -' to
  remove that predicate.)  With a prefix arg it can also set or
  save (i.e., do what `M-? !' or `M-? s' does).

* `M-? M-h' (`isearchp-show-filters') echoes the current suite
  of filter predicates (advice and original, unadvised
  predicate).

* `M-? @', `M-? <', and `M-? >' (`isearchp-near',
  `isearchp-near-before', and `isearchp-near-after') constrain
  searching to be within a given distance of (near) another
  search pattern.

When you use one of the commands that adds a filter predicate as
advice to `isearch-filter-predicate' you can be prompted for two
things: (1) a name for the predicate and (2) text to add to the
Isearch prompt as a reminder of filtering.  Two user options
control this prompting:

* `isearchp-prompt-for-filter-name' says whether to prompt you
  always, never, or only when the predicate that you provide is
  not a symbol (it is a lambda form).  The last of these is the
  default behavior.  If you are prompted and provide a name, you
  can use that name with `M-? -' to remove that predicate.

* `isearchp-prompt-for-isearch-prompt-prefix' says whether to
  prompt you for a prefix to add to the Isearch prompt.  You are
  prompted by default, but if you don't care to see such a
  prompt prefix and you don't want to be bothered by it, you can
  customize this to skip prompting.

In addition, whatever the value of these options, when you add a
filter predicate you can override the option values by using a
prefix argument.  A non-positive prefix arg overrides the option
for name prompting, and a non-negative prefix arg overrides the
option for prompt-prefix prompting.  (So zero, e.g., `M-0',
overrides both.)

(The code is here, if anyone wants to play with it:
https://www.emacswiki.org/emacs/download/isearch%2b.el)

Re: 1) (elisp) `Advising Named Functions', 2) search filtering example

[Noam Postavsky]

On Mon, Oct 17, 2016 at 1:25 AM, Drew Adams <drew.adams@oracle.com> wrote:
> 1. Node `Advising Named Functions' of the Elisp manual says this:
>
>  For these reasons, advice should be reserved for the cases
>  where you cannot modify a function’s behavior in any other way.
>  If it is possible to do the same thing via a hook, that is
>  preferable. ...
>
>  In particular, Emacs’s own source files should not put advice
>  on functions in Emacs.  (There are currently a few exceptions
>  to this convention, but we aim to correct them.)
>
> Is that still true?  Is this the policy, even with the new
> advice system?
>
> If so, then it seems that it is being ignored, as new advice
> has been added to `isearch-filter-predicate' in `dired-aux.el'
> and `wdired.el'.

`advice-add' puts advice on a function, `add-function' does not.
`isearch-filter-predicate' is not a function, it's a variable
containing a function value.

RE: 1) (elisp) `Advising Named Functions', 2) search filtering example

[Drew Adams]

> `advice-add' puts advice on a function, `add-function'
> does not.

I don't think so.  AFAICS, `add-function' certainly does
"put advice on a function".

`advice-add' is essentially `add-function' for a _named_
function.  It does not apply to lambda forms etc.  It is
a wrapper around `add-function' that also deals with the
symbol itself (e.g. adding doc, handling macro symbols,...).

But you raise a reasonable point about that doc.  AFAICT,
nearly everything that is said in that node about potential
problems and reserving advice for when you cannot modify a 
function's behavior any other way applies just as well to
`add-function' etc. as to `advice-add' etc.

AFAICS, that info and advice is about advising functions.
It is not just about advising named functions, and even if
it were, it should apply equally to `add-function' for a
named function.

Do you think that that information does not apply also
to this code, from dired-aux.el?  If so, why?

(add-function :before-while (local 'isearch-filter-predicate)
              #'dired-isearch-filter-filenames
              '((isearch-message-prefix . "filename ")))

(The local value of `isearch-filter-predicate' can of
course be a named function.  But it need not be.)

> `isearch-filter-predicate' is not a function, it's a
> variable containing a function value.

Yes, I know that.  (And its value is not necessarily a
symbol.)

Re: 1) (elisp) `Advising Named Functions', 2) search filtering example

[Noam Postavsky]

On Mon, Oct 17, 2016 at 10:02 AM, Drew Adams <drew.adams@oracle.com> wrote:
>> `advice-add' puts advice on a function, `add-function'
>> does not.
>
> I don't think so.  AFAICS, `add-function' certainly does
> "put advice on a function".

You're right. I did have the impression that add-function was
considered to be okay, just like add-hook is. But the manual doesn't
say this (and also, I didn't realize that (add-function
...(symbol-function 'FUN)...) has almost the same effect as
advice-add). So I was wrong to look at add-function vs advice-add; the
important distinction is between the thing being added to, not the
function used to do the adding.

>
> Do you think that that information does not apply also
> to this code, from dired-aux.el?  If so, why?
>
> (add-function :before-while (local 'isearch-filter-predicate)
>               #'dired-isearch-filter-filenames
>               '((isearch-message-prefix . "filename ")))

I think it falls under this case in `(elisp) Hooks' (which should be
updated to mention `-predicate' as a possible suffix)

       If the variable’s name ends in ‘-function’, then its value is just a
    single function, not a list of functions.  ‘add-hook’ cannot be used to
    modify such a _single function hook_, and you have to use ‘add-function’
    instead (*note Advising Functions::).

Re: 1) (elisp) `Advising Named Functions', 2) search filtering example

[Stefan Monnier]

> You're right. I did have the impression that add-function was
> considered to be okay, just like add-hook is.

It is.

> the important distinction is between the thing being added to, not the
> function used to do the adding.

That's right.  For `foo-predicate` and `foo-bar-function`, modifying the
variable is the raison d'être of that variable, so it's not harmful:
programmers know that by design this value may change.

On the contrary (symbol-function <foo>) is the value associated to
a function name and programmers usually expect that function to be
defined at somewhere in a file (in a single place) and the value is
expected (by the programmer and by other chunks of code which call it)
to be faithful to the file's code.


        Stefan

RE: 1) (elisp) `Advising Named Functions', 2) search filtering example

[Drew Adams]

> > You're right. I did have the impression that add-function was
> > considered to be okay, just like add-hook is.
> 
> It is.
> 
> > the important distinction is between the thing being added to, not the
> > function used to do the adding.
> 
> That's right.  For `foo-predicate` and `foo-bar-function`, modifying the
> variable is the raison d'être of that variable, so it's not harmful:
> programmers know that by design this value may change.

But advising such a variable also advises its function value.

Applying macro `add-function' to `isearch-filter-predicate'
advises the value - the function itself.  It does not just
point the variable to a different value (function).  This is
a bit different from just saying that because the variable
has a function value users will expect the variable value
to be changeable.

To be clear, I don't think I have a problem with a policy
change that says that advising is now OK also for Emacs
itself.  But I think the policy should be recognized if this
is the case, and the doc should reflect it.
 
> On the contrary (symbol-function <foo>) is the value associated to
> a function name and programmers usually expect that function to be
> defined at somewhere in a file (in a single place) and the value is
> expected (by the programmer and by other chunks of code which call it)
> to be faithful to the file's code.

If you advise either `isearch-filter-predicate' (as a place)
or its value (e.g. `isearch-filter-visible') then
`(symbol-function isearch-filter-predicate)' returns an advice
(an object that satisfies "internal" predicate `advice--p').

The doc commands pretty much DTRT (but see bug #14734).  But
the function that is the value of an advised function variable
such as `isearch-filter-predicate' _is advised_, and its
`symbol-function' reflects that.

(In fact, to retrieve the name of the function that is
advised, you need to do some digging (e.g., use "internal" and
undocumented function `advice--cd*r').

Re: 1) (elisp) `Advising Named Functions', 2) search filtering example

[Stefan Monnier]

> Applying macro `add-function' to `isearch-filter-predicate'
> advises the value - the function itself.

No.

> It does not just
> point the variable to a different value (function).

Yes it does.

> `(symbol-function isearch-filter-predicate)' returns an advice
> (an object that satisfies "internal" predicate `advice--p').

No, it returns nil because this symbol is not defined as a function.


        Stefan

RE: 1) (elisp) `Advising Named Functions', 2) search filtering example

[Drew Adams]

> > Applying macro `add-function' to `isearch-filter-predicate'
> > advises the value - the function itself.
> No.
> 
> > It does not just point the variable to a different value
> > (function).
> Yes it does.

OK.

> > `(symbol-function isearch-filter-predicate)' returns an advice
> > (an object that satisfies "internal" predicate `advice--p').
> 
> No, it returns nil because this symbol is not defined as a function.

I did not quote that symbol.  But yes, you get an error because
the value of the variable is _not_ a symbol (anymore) - it is now
an advice object (an advised function, I was calling it).  It is a
thingy such as this - an advice of function `isearch-filter-visible'.

#[128 <some-byte-code> [apply (lambda (b e) (save-excursion
(goto-char e) (eolp))) isearch-filter-visible ((name . "eol")
(isearch-message-prefix . "eol, "))] 4 nil]

Dunno what you want to call such a thing.  I was calling it
an advised function (in this case, `isearch-filter-visible')
and an advice of that function, but yes, that function is not
advised outside this context - it is only variable
`isearch-filter-predicate' that uses that thingy.

To me, the new advice doc is not as helpful as it should be,
and the thingies dealt with are not clear or clearly presented.
Even the resort to "internalizing" functions such as `advice--p'
and `advice--cd*r' seems unfortunate.

I'm sure you understand it all very well, and no doubt there
are things about it that I do not understand well.  If you
cannot or will not, I'm still hoping that someone else will
improve the doc and make things clearer, for all.

Re: 1) (elisp) `Advising Named Functions', 2) search filtering example

[Stefan Monnier]

> #[128 <some-byte-code> [apply (lambda (b e) (save-excursion
> (goto-char e) (eolp))) isearch-filter-visible ((name . "eol")
> (isearch-message-prefix . "eol, "))] 4 nil]
> Dunno what you want to call such a thing.

A function object (a closure).  More specifically a function which is
the composition of two or more functions.  You could get a similar
function without using add-function, but using instead something like

    (setq isearch-filter-predicate
          (let ((old isearch-filter-predicate))
            (lambda (&rest args)
              (and (apply <f> args)
                   (apply old args)))))

> To me, the new advice doc is not as helpful as it should be,
> and the thingies dealt with are not clear or clearly presented.

To me, they're not as obscure as they should be: in my world, functions
are black boxes (you only get to know their type).

If you do

   (setq isearch-filter-predicate (symbol-function isearch-filter-predicate))

you end up with a variable that behaves pretty much exactly as before,
but if you look at the value of `isearch-filter-predicate` it will
suddenly look like some gobbledygook as well.  The fact that sometimes
you get a symbol is just an accident.

> If you cannot or will not, I'm still hoping that someone else will
> improve the doc and make things clearer, for all.

I have no idea how to improve the doc, so feel free to try and do it.
In the past I've had some luck with a "generate&test" approach, where
someone writes a tentative doc, and I point out the factual errors in it,
repeating the process until the doc is both understandable and correct.


        Stefan

RE: 1) (elisp) `Advising Named Functions', 2) search filtering example

[Drew Adams]

> > Do you think that that information does not apply also
> > to this code, from dired-aux.el?  If so, why?
> >
> > (add-function :before-while (local 'isearch-filter-predicate)
> >               #'dired-isearch-filter-filenames
> >               '((isearch-message-prefix . "filename ")))
> 
> I think it falls under this case in `(elisp) Hooks' (which should be
> updated to mention `-predicate' as a possible suffix)
> 
>        If the variable’s name ends in ‘-function’, then its value is just
>     a single function, not a list of functions.  ‘add-hook’ cannot be used
>     to modify such a _single function hook_, and you have to use
>     ‘add-function’ instead (*note Advising Functions::).

I think that is wrong also.  `add-hook' _can_ be used to modify a _single
function hook_.  And the doc of `add-hook' tells you so, in its last line -
`C-h f add-hook':

  ...
  If HOOK's value is a single function, it is changed to a list of
  functions.

Again, I do question whether we should now be advising against using
hooks and in favor of the new advice.  But I guess I'm OK with that,
if it's really the decision.  As I mentioned, I already took the
latter approach in my Isearch filtering feature.

Re: 1) (elisp) `Advising Named Functions', 2) search filtering example

[Noam Postavsky]

On Mon, Oct 17, 2016 at 11:40 AM, Drew Adams <drew.adams@oracle.com> wrote:

> I think that is wrong also.  `add-hook' _can_ be used to modify a _single
> function hook_.  And the doc of `add-hook' tells you so, in its last line -
> `C-h f add-hook':
>
>   ...
>   If HOOK's value is a single function, it is changed to a list of
>   functions.

If you do this, then you will break the callers, which expect the
value of this variable to be a single function.

RE: 1) (elisp) `Advising Named Functions', 2) search filtering example

[Drew Adams]

> > I think that is wrong also.  `add-hook' _can_ be used to modify a
> > _single function hook_.  And the doc of `add-hook' tells you so,
> > in its last line - `C-h f add-hook':
> >
> >   ...
> >   If HOOK's value is a single function, it is changed to a list of
> >   functions.
> 
> If you do this, then you will break the callers, which expect the
> value of this variable to be a single function.

Tell that to the doc string for `add-hook', which has said what it
says in this regard for a very long time.

What has changed (what is new) is that this was added to node `Hooks':

  If the variable’s name ends in ‘-function’, then its value is
  just a single function, not a list of functions.  ‘add-hook’
  cannot be used to modify such a _single function hook_, and you
  have to use ‘add-function’ instead (*note Advising Functions::).

And that is clearly false ("cannot be used" - it _can_ be so used).

This is what that doc used to say (e.g. Emacs 23.4):

   By convention, abnormal hook names end in `-functions' or
   `-hooks'.  If the variable's name ends in `-function', then
   its value is just a single function, not a list of functions.

There has thus also (apparently) been a change in policy here.
Whereas, before, this doc just let you know about the _naming
convention_ for a hook whose value is a single function, the
changed doc says (incorrectly) that you cannot use `add-hook'
with it.

I think that callers of such a hook should _use it as a hook_,
and not necessarily expect that the value is a single function.

Callers of a hook can, and should, I think, use one of the
`run-hook*' functions.  And there too you will note that the
doc _explicitly_ talks about the non-list, single function case.

`C-h f run-hooks':

  If a hook symbol has a non-nil value, that value may be a
  function or a list of functions to be called to run the hook.
  If the value is a function, it is called with no arguments.
  If it is a list, the elements are called, in order, with no arguments.

`C-h f run-hook-with-args':

  The value of HOOK may be nil, a function, or a list of functions.
  Call each function in order with arguments ARGS.

(It used to say this:

  If HOOK has a non-nil value, that value may be a function
  or a list of functions to be called to run the hook.  If the
  value is a function, it is called with the given arguments
  and its return value is returned.  If it is a list of functions,
  those functions are called, in order, with the given arguments ARGS.)

`C-h f run-hook-with-args-until-failure':

  The value of HOOK may be nil, a function, or a list of functions.
  Call each function in order with arguments ARGS, stopping at the
  first one that returns nil, and return nil.

`C-h f run-hook-with-args-until-success': similar.

So do we have changes in policy wrt using hooks, or not?
(If yes, why?)  Which doc needs to be fixed?

Re: 1) (elisp) `Advising Named Functions', 2) search filtering example

[Stefan Monnier]

>> If you do this, then you will break the callers, which expect the
>> value of this variable to be a single function.
> Tell that to the doc string for `add-hook', which has said what it
> says in this regard for a very long time.

There is no contradiction between the two.  `add-hook's doc talks about
the case where a "multiple-function hook" has a value which happens to
be a single function (which is an acceptable value for those hooks, for
historical reasons).

Whereas we're here talking about "single-function hooks", i.e. variables
which should only ever hold a single function and not a list of functions.
You can use (add-hook <hook> <function>) on them, just like you can use
(setq <hook> 5) on them.  That doesn't mean that it's correct to do so.


        Stefan

RE: 1) (elisp) `Advising Named Functions', 2) search filtering example

[Drew Adams]

> >> If you do this, then you will break the callers, which expect the
> >> value of this variable to be a single function.
> >
> > Tell that to the doc string for `add-hook', which has said what it
> > says in this regard for a very long time.
> 
> There is no contradiction between the two.  `add-hook's doc talks about
> the case where a "multiple-function hook" has a value which happens to
> be a single function (which is an acceptable value for those hooks, for
> historical reasons).

That's one interpretation.  There is no mention of the fact that
the hook it is talking about is necessarily a "multiple-function
hook" that happens to have a single function as value.

> Whereas we're here talking about "single-function hooks", i.e. variables
> which should only ever hold a single function and not a list of functions.
>
> You can use (add-hook <hook> <function>) on them, just like you can use
> (setq <hook> 5) on them.  That doesn't mean that it's correct to do so.

If you say so.  Who decided it is incorrect, and why?  As I noted,
previously it was not a no-no to use `add-hook' on such a hook,
and `add-hook' was specifically designed to handle the case of a
single function (whether "'multiple-function hook' that happens
to have a single function as value" or "single-function hook").

And unlike what you just said (you can but it is not correct to
do so - or is it just not necessarily correct?), the doc now says:

 "‘add-hook’ cannot be used to modify such a _single function
             ^^^^^^^^^^^^^^
  hook_, and you have to use ‘add-function’ instead (*note
                 ^^^^^^^^^^^
  Advising Functions::)."

I wonder who added that sentence. ;-)

Re: 1) (elisp) `Advising Named Functions', 2) search filtering example

[Stefan Monnier]

> That's one interpretation.  There is no mention of the fact that
> the hook it is talking about is necessarily a "multiple-function
> hook" that happens to have a single function as value.

That's because you misunderstand its doc.  The confusion comes from the
multiple uses of the name "hook".  There are basically two uses of
the word "hook" in the context of Emacs:

- a very generic sense, which refers to some kind of way to influence
  the behavior of something.  Used also sometimes as a verb "you can
  hook directly into ..." which might be used even in cases where the
  "hooking" is done by modifying some chunk of code.  Sometimes
  "hook" is even used to just mean a customization point ("that package
  doesn't give me any hook to specify which char to insert").
- a specific sense, which refers to an "object" implemented as a symbol
  where the symbol-value slot holds a list of functions (and the "hook"
  is really the symbol, not the list of functions, because we can also use
  its various buffer-local values).

The second subsumes the first.

So *-function is a hook in the first sense but not in the second.
Whereas *-functions and *-hook are hooks in both senses.
add-hook and remove-hook only apply to hooks in the second sense.

The advice mechanism treats every symbol's function definition as a hook
(in the first sense), whether the author intended it that way (as is the
case for `ask-user-about-supersession-threat') or not.


        Stefan

Re: 1) (elisp) `Advising Named Functions', 2) search filtering example

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > That's because you misunderstand its doc.  The confusion comes from the
  > multiple uses of the name "hook".  There are basically two uses of
  > the word "hook" in the context of Emacs:

The job of documentation is to be understood.  If a user who is
generally sensible misunderstands a certain point, that's not per
fault, it's the documentation's fault.

Can we discourage the more general meaning of "hook"?

  > the word "hook" in the context of Emacs:

  > - a very generic sense, which refers to some kind of way to influence
  >   the behavior of something.

Is there anything in our manuals that encourages this conflicting sense
of the word?

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

Re: 1) (elisp) `Advising Named Functions', 2) search filtering example

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Tue, 18 Oct 2016 15:47:35 -0400
> Cc: drew.adams@oracle.com, emacs-devel@gnu.org
> 
>   > - a very generic sense, which refers to some kind of way to influence
>   >   the behavior of something.
> 
> Is there anything in our manuals that encourages this conflicting sense
> of the word?

Most probably, because "hook" is a general-purpose word freely used in
general discourse.  I don't see how can we avoid that without having
complicated confusing text in the manual.

I think Stefan didn't mention one more meaning of "hook" that is
specific to Emacs: it is sometimes used in reference to the function
that gets placed on the list that is the value of a hook variable.
(Actually, to my mind, this is the only situation where something
should be called "a hook".)

Re: 1) (elisp) `Advising Named Functions', 2) search filtering example

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > I think Stefan didn't mention one more meaning of "hook" that is
  > specific to Emacs: it is sometimes used in reference to the function
  > that gets placed on the list that is the value of a hook variable.
  > (Actually, to my mind, this is the only situation where something
  > should be called "a hook".)

Don't we use the term "hook function" for these?

  > Most probably, because "hook" is a general-purpose word freely used in
  > general discourse.  I don't see how can we avoid that without having
  > complicated confusing text in the manual.

Let's try it and see what changes would be required.

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

Re: 1) (elisp) `Advising Named Functions', 2) search filtering example

[Stefan Monnier]

>> Most probably, because "hook" is a general-purpose word freely used in
>> general discourse.  I don't see how can we avoid that without having
>> complicated confusing text in the manual.

> Let's try it and see what changes would be required.

FWIW, I'm not eve sure the confusion comes from the manual.
The informal use of `hook` to which I was referring is one I use and see
in email mostly.  It's very widespread, AFAICT, but that doesn't mean
the manual isn't more careful.


        Stefan

Re: 1) (elisp) `Advising Named Functions', 2) search filtering example

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Wed, 19 Oct 2016 16:18:59 -0400
> 
> >> Most probably, because "hook" is a general-purpose word freely used in
> >> general discourse.  I don't see how can we avoid that without having
> >> complicated confusing text in the manual.
> 
> > Let's try it and see what changes would be required.
> 
> FWIW, I'm not eve sure the confusion comes from the manual.
> The informal use of `hook` to which I was referring is one I use and see
> in email mostly.  It's very widespread, AFAICT, but that doesn't mean
> the manual isn't more careful.

Exactly my thoughts, yes.

Re: 1) (elisp) `Advising Named Functions', 2) search filtering example

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> CC: monnier@IRO.UMontreal.CA, drew.adams@oracle.com,
> 	emacs-devel@gnu.org
> Date: Wed, 19 Oct 2016 16:00:53 -0400
> 
>   > I think Stefan didn't mention one more meaning of "hook" that is
>   > specific to Emacs: it is sometimes used in reference to the function
>   > that gets placed on the list that is the value of a hook variable.
>   > (Actually, to my mind, this is the only situation where something
>   > should be called "a hook".)
> 
> Don't we use the term "hook function" for these?

Adding that word makes the text longer, so many times we don't.

Re: 1) (elisp) `Advising Named Functions', 2) search filtering example

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > Don't we use the term "hook function" for these?

  > Adding that word makes the text longer, so many times we don't.

Come to think of it, the names add-hook and remove-hook
also refer to that function as a hook.

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.