bug#55527: 28.1; Clearer abbrev docstrings

[Howard Melman]

Eli Zaretskii <eliz@gnu.org> writes:

>> 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 think you can loose the "mode-independent" part, as global
covers that pretty clearly, how about:

   Define last word before point as expansion of a global 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.

Yes but I'm adding about 10 characters to the prompt, so
once you get to "arbitrarily long", 10 characters only
affects so many of them :)

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

Yes that was *my* point.  The original says:

Define an abbrev in TABLE named NAME, to expand to EXPANSION and call HOOK.

which to me doesn't answer "by whom and when" and I think is
actually less clear than my rewording.  Perhaps better is:

  Define in TABLE an ABBREV and its EXPANSION and optionally its HOOK.

I don't think it's at all obvious how the original clauses
relate to each other (thankfully the full docstring is much
clearer) but as you brought up non-native english speakers I
would think the original is also difficult for them.

-- 

Howard