bug#55527: 28.1; Clearer abbrev docstrings

[Howard Melman]

When using abbrev commands I'm always confused by which 
is the abbrev and which is the expansion.  I think there are a 
few reasons for this.

I know that the manual defines "abbrev" as the short name, but given
it's the package and feature name I also think of it as an overused
term for the pairing of an abbreviation and its expansion.  With this
confusion some of the prompts and command names are easily read as
ambiguous.  (I'll talk about the global forms here but they all apply
to the mode-specific forms too.)

First off, I don't define abbrevs frequently enough to
remember their bindings, so I usually use M-x.  The names of
the commands add-global-abbrev and inverse-add-global-abbrev
also don't resolve the ambiguity, since all they say is one
is the inverse of the other.  I know these are very old
commands, but a clearer alias of the latter could be one of:

    add-global-expansion
    add-global-abbrev-expansion
    add-global-expansion-of-abbrev

I use marginalia so I see annotations when using M-x which
include the first line of the commands' docstring.  The
first line of the docstrings for add-global-abbrev and
inverse-add-global-abbrev don't help me too much.  They are
currently:

    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 word before point as the abbreviation of a new global abbrev.

The latter could also be this (though it's 70 chars long):

    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.  Even if it did this
occasionally I think it would help.

Then, if I do pick one of the commands the prompts don't
give me confidence I chose the right one.  These are the
interactive prompts for add-global-abbrev and
inverse-add-global-abbrev:

        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":

(I'm not sure if "of" or "for" read better in either of the above).
Or even better:

        Global abbrev to expand to "foo":
        Expand global abbrev "foo" to:

Finally define-abbrev has an argument "name" that I find too generic
and a docstring first line I find awkward.  Perhaps change this:

        (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.

(and of course the two uses of the variable name in the
function which I think will read much clearer.)

Howard