bug#55527: 28.1; Clearer abbrev docstrings

[Eli Zaretskii]

> From: Howard Melman <hmelman@gmail.com>
> Date: Thu, 19 May 2022 14:32:44 -0400
> 
>     Define global (all modes) abbrev for last word(s) before point.
>     Define last word before point as a global (mode-independent) abbrev.
> 
> and I find I have to think hard to resolve which is which. I
> think these would be clearer:
> 
>     Use word(s) before point as the expansion of a new global abbrev.

"Use" is ambiguous, because it may be interpreted as "expand it now".
"Define" is better.  So I would suggest

  Define a global abbrev that expands into word(s) preceding point.

>     Use word before point as the abbreviation of a new global abbrev.

"Abbreviation of a new abbrev" is confusing.  I don't actually
understand what's wrong with the original one, viz.:

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

>     Define word before point as a global abbrev, prompt for its expansion.
> 
> FWIW I do wish the documentation used "abbreviation" when it refers to
> the abbrev so that "abbrev" could refer to the pair of "abbreviation"
> and "expansion" or to the feature name.

That'd be counter-productive, because it will cause these doc strings
become longer and more confusing.

>       Global abbrev for "foo":
>       Global expansion for "foo":
> 
> The latter is fine but the first confuses me (particularly
> when defining one word expansions), I think these would be
> clearer as:
> 
>       Global abbrev for expansion "foo":
>       Global expansion of abbrev "foo":

Is that really more clear?  I would say

  Global abbrev that expands into "foo":
  Expansion for a global abbrev "foo":

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.

>       (defun define-abbrev (table name expansion &optional hook &rest props)
>         "Define an abbrev in TABLE named NAME, to expand to EXPANSION and 
> call HOOK.
> 
> to this:
> 
>       (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.