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

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

[Drew Adams]

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'

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

[Andreas Röhler]

On 25.09.2016 16:53, Drew Adams wrote:
> Let's check the doc, starting with `expand-abbrev':
>
>

Hi Drew,

thanks. abbrev.el needs a reconsideration from the bottom. Discussed 
this several weeks ago at emacs-devel. A re-write IMHO must start with 
specifications, i.e. it must be known, what to expect.

Being in favor of accepting arbitrary, case-sensitive strings as abbrev, 
which seems not working at the moment.

Cheers,
Andreas

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

[Drew Adams]

> Hi Drew,
> 
> thanks. abbrev.el needs a reconsideration from the bottom. Discussed
> this several weeks ago at emacs-devel. A re-write IMHO must start with
> specifications, i.e. it must be known, what to expect.
> 
> Being in favor of accepting arbitrary, case-sensitive strings as abbrev,
> which seems not working at the moment.

Hi Andreas,

OK, but maybe this doc could be cleared up a bit first,
as a minor improvement.

 - Drew

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

[Andreas Röhler]

On 25.09.2016 16:53, Drew Adams wrote:
> 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'.)

Hmm, the explicit "-function" tells me, there is something uncommon: ah, 
that's not a function at this level.

OTOH a thing would be to name a function  "-function".
But these are conventions, which also apply to other parts.
Think it's worth to be brought to emacs-devel.

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

[Eli Zaretskii]

> Date: Sun, 25 Sep 2016 07:53:30 -0700 (PDT)
> From: 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."

Actually, it says this:

    "Expand the abbrev before point, if there is an abbrev there.
  Effective when explicitly called even when `abbrev-mode' is nil.
  Before doing anything else, runs `pre-abbrev-expand-hook'.
  Calls `abbrev-expand-function' with no argument to do the work,
  and returns whatever it does.  (This should be the abbrev symbol
  if expansion occurred, else nil.)"

IOW, it (1) describes what the command does, (2) mentions the function
it calls to do the actual work, and (3) explains what "whatever"
means.  Quite a lot less mysterious than what the single sentence you
presented might convey, IMO.

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

Yes, fixed.

> So we look at `abbrev-expand-function', which tells us that the default
> value is `abbrev--default-expand'.

Given the above description, I see no reason for looking at
abbrev-expand-function at all, as no information is missing.  But
let's play along nonetheless.

> (Why the default value of such a presumably user-modifiable variable
> should be considered an "internal" function is a mystery.)

Why not?  It's just a value, right?  The user-modifiable part is not
the value, it's the variable abbrev-expand-function, which is not
internal.

> So we look at `abbrev--default-expand', which tells us this:
> 
> "This respects the wrapper hook `abbrev-expand-functions'."

No, it tells this:

    "Default function to use for `abbrev-expand-function'.
  This respects the wrapper hook `abbrev-expand-functions'.
  Calls `abbrev-insert' to insert any expansion, and returns what it does."

So it mentions the (non-obsolete) variable abbrev-expand-function, and
only then tells you that it _also_ respects the obsolete hook
abbrev-expand-functions.  Again, quite a different picture.

(I fixed the doc string to say "also" and "obsolete" explicitly.)

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

Not quite accurate, to say the least.  In particular, the non-obsolete
variable was mentioned _before_ the obsolete one in the first place.

> 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 isn't documented in the manuals because it's an obsolete feature.
I added references to with-wrapper-hook to the few doc strings that
were referencing wrapper hooks (there were just 4 of them in all of
Emacs).

(The text of your report was repeated 3 times for some reason.)