bug#55527: 28.1; Clearer abbrev docstrings

[Howard Melman]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Howard Melman <hmelman@gmail.com>
>>     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.

I think that's good.

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

Because I'm not sure if the word will be used as the abbrev
or the expansion.

>>     Define word before point as a global abbrev, prompt for its expansion.

The above makes it clear, what do you think of it?

>>      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 think so, because both make it clear what "foo" will be
used for.

> 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.  For those that
expand them to something longer, these aren't that much
longer prompts so the window they would break (expansions
long enough to break but short enough not be broken before)
doesn't seem large to me.

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

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.  I think mine makes it slightly
clearer that it's associated with the persisted definition
rather than called when the define-abbrev is called.

And while I agree "Define in TABLE" is a little (not very)
awkward, I think it's less awkard than the original, where
NAME could be the name of the abbrev or of the TABLE.

Also the original was 75 chars long and mine fits in the
recommendated 67 character length.

Maybe someone has a better suggestion, but I think changing
"name" to "abbrev" is worth doing.

Also I think the docstring should say define-abbrev returns
"name" (hopefully changed to "abbrev").

Howard