bug#55527: 28.1; Clearer abbrev docstrings

[Eli Zaretskii]

> From: Howard Melman <hmelman@gmail.com>
> Date: Thu, 19 May 2022 16:38:42 -0400
> 
> > 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.

No, "global" doesn't explain itself in this case, because we aren't
talking about a minor mode.  So I'd rather lose "a" or even replace
"of a" with "for".  We could also lose "last".

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

Yes, it does: the abbrev you define will call HOOK at the time of the
expansion.  That's what the sentence says.

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

"Define in TABLE" is awkward (or even incorrect) English.  OTOH,
"optionally" is redundant, so maybe if we lose it, we could reword the
sentence to be more correct English-wise.

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

The comparison is always relative, not absolute.  And if the full doc
string makes things clear, it's fine.