bug#55527: 28.1; Clearer abbrev docstrings

[Eli Zaretskii]

> From: Howard Melman <hmelman@gmail.com>
> Date: Thu, 19 May 2022 15:30:18 -0400
> 
> > I don't actually understand what's wrong with the original one,
> > viz.:
> >
> >   Define last word before point as a global (mode-independent) abbrev.
> 
> Because I'm not sure if the word will be used as the abbrev
> or the expansion.

If you add the expansion part, the line becomes too long, though:

  Define last word before point as expansion of a global (mode-independent) 
abbrev.

> > I would say
> >
> >   Global abbrev that expands into "foo":
> >   Expansion for a global abbrev "foo":
> 
> Those would be fine with me.
> 
> > But I'm not sure we can make these prompts so much longer than the
> > original ones without overflowing the minibuffer into a second line,
> > which is a disadvantage.
> 
> I tend to use very short abbrevs that expand into longer
> words, so it wouldn't be a problem for me.

The problem in the first prompt is with "foo": it could be arbitrarily
long.  And in the second prompt you are supposed to type the
expansion, which again can be long.

> >>    (defun define-abbrev (table abbrev expansion &optional hook &rest props)
> >>      "Define in TABLE an ABBREV and its EXPANSION and optionally a HOOK.
> >
> > This loses the explanation of what is HOOK, and is also a very awkward
> > sentence that I think will be hard on non-native English
> > speakers.
> 
> I'm not sure that "call HOOK" is an "explanation".  I
> already assumed a "hook" would be called and I was confused
> when it would be called.

It will be called, but by whom and when?