bug#24540: 25.1; doc of `abbrev-expand-function(s)', "wrapper hooks",...

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

Let's check the doc, starting with `expand-abbrev':

"Calls `abbrev-expand-function' with no argument to do the work, and
returns whatever it does."

(It should say that it calls the _value of variable_
`abbrev-expand-function'.)

So we look at `abbrev-expand-function', which tells us that the default
value is `abbrev--default-expand'.  (Why the default value of such a
presumably user-modifiable variable should be considered an "internal"
function is a mystery.)

So we look at `abbrev--default-expand', which tells us this:

"This respects the wrapper hook `abbrev-expand-functions'."

Hm.  So we look at `abbrev-expand-functions', to see what this "wrapper
hook" is all about.  It tells us this:

"Wrapper hook around ‘abbrev--default-expand’."

OK.  It's a "wrapper hook", whatever that is.  This doesn't tell us
anything more.

But `C-h v abbrev-expand-functions' also tells us this, which is
interesting:

"This variable is obsolete since 24.4; use ‘abbrev-expand-function’
instead."

So the doc tells us about a "wrapper hook", which is presumably
something like a hook, which is something that users can use.  But the
wrapper hook we are pointed to is "obsolete", and we are told to instead
use a different variable (sans "s") - which was the one we started with!
Round and round we go...

Now what about the mysterious term "wrapper hook", apparently introduced
fairly recently?  Searching for it in the Emacs manual shows nothing.
Searching for it in the Elisp manual shows only mentions of particular
"obsolete" wrapper hooks - no explanation of what is meant by a "wrapper
hook".

It looks as though a new term ("wrapper hook") was introduced to the
Emacs vocabulary in Emacs 23, and then removed (deprecated?) soon
thereafter.  What is this all about?  What is a poor user to understand
about all of this?

One could forgive a user for being confused, or totally lost, in this
swamp.  Please consider clearing away some of the brambles.


In GNU Emacs 25.1.1 (x86_64-w64-mingw32)
 of 2016-09-17 built on LAPHROAIG
Windowing system distributor 'Microsoft Corp.', version 6.1.7601
Configured using:
 'configure --without-dbus --without-compress-install CFLAGS=-static'


Let's check the doc, starting with `expand-abbrev':

"Calls `abbrev-expand-function' with no argument to do the work, and
returns whatever it does."

So we look at `abbrev-expand-function', which tells us that the default
value is `abbrev--default-expand'.  (Why the default value of such a
user-modifiable variable should be considered an "internal" function is
a mystery.)

So we look at `abbrev--default-expand', which tells us this:

"This respects the wrapper hook `abbrev-expand-functions'."

Hm.  So we look at `abbrev-expand-functions', to see what this "wrapper
hook" is all about.  It tells us this:

"Wrapper hook around ‘abbrev--default-expand’."

OK.  It's a "wrapper hook", whatever that is.  This doesn't tell us
anything more.

But `C-h v abbrev--default-expand' also tells us this, which is
interesting:

"This variable is obsolete since 24.4; use ‘abbrev-expand-function’
instead."

So the doc tells us about a "wrapper hook", which is presumably
something like a hook, which is something that users can use.  But the
wrapper hook we are pointed to is "obsolete", and we are told to instead
use a different variable (sans "s") - which was the one we started with!
Round and round we go.

So what about the mysterious term "wrapper hook", apparently introduced
fairly recently?  Searching for it in the Emacs manual shows nothing.
Searching for it in the Elisp manual shows only mentions of particular
"obsolete" wrapper hooks - no explanation of what is meant by a "wrapper
hook".

It looks as though a new term ("wrapper hook") was introduced to the
Emacs vocabulary recently, and then removed (deprecated?) almost
immediately.  What is this all about?  What is a poor user to understand
about all of this?

One could forgive a user for being confused, or totally lost, in this
swamp.




In GNU Emacs 25.1.1 (x86_64-w64-mingw32)
 of 2016-09-17 built on LAPHROAIG
Windowing system distributor 'Microsoft Corp.', version 6.1.7601
Configured using:
 'configure --without-dbus --without-compress-install CFLAGS=-static'


So we look at `abbrev-expand-function', which tells us that the default
value is `abbrev--default-expand'.  (Why the default value of such a
user-modifiable variable should be considered an "internal" function is
a mystery.)

So we look at `abbrev--default-expand', which tells us this:

"This respects the wrapper hook `abbrev-expand-functions'."

Hm.  So we look at `abbrev-expand-functions', to see what this "wrapper
hook" is all about.  It tells us this:

"Wrapper hook around ‘abbrev--default-expand’."

OK.  It's a "wrapper hook", whatever that is.  This doesn't tell us
anything more.

But `C-h v abbrev--default-expand' also tells us this, which is
interesting:

"This variable is obsolete since 24.4; use ‘abbrev-expand-function’
instead."

So the doc tells us about a "wrapper hook", which is presumably
something like a hook, which is something that users can use.  But the
wrapper hook we are pointed to is "obsolete", and we are told to instead
use a different variable (sans "s") - which was the one we started with!
Round and round we go.

So what about the mysterious term "wrapper hook", apparently introduced
fairly recently?  Searching for it in the Emacs manual shows nothing.
Searching for it in the Elisp manual shows only mentions of particular
"obsolete" wrapper hooks - no explanation of what is meant by a "wrapper
hook".

It looks as though a new term ("wrapper hook") was introduced to the
Emacs vocabulary recently, and then removed (deprecated?) almost
immediately.  What is this all about?  What is a poor user to understand
about all of this?

One could forgive a user for being confused, or totally lost, in this
swamp.


In GNU Emacs 25.1.1 (x86_64-w64-mingw32)
 of 2016-09-17 built on LAPHROAIG
Windowing system distributor 'Microsoft Corp.', version 6.1.7601
Configured using:
 'configure --without-dbus --without-compress-install CFLAGS=-static'