bug#55527: 28.1; Clearer abbrev docstrings

[Eli Zaretskii]

> From: Howard Melman <hmelman@gmail.com>
> Date: Fri, 20 May 2022 09:35:43 -0400
> 
> >>    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".
> 
> To kind of prove my point, we've confused the docstrings of
> the two commands :) The command that only uses the last word
> (as opposed to possibly several words) of the buffer text
> uses that word as the abbrev not the expansion.

Is that relevant for the "global" issue to which I responded?

> Maybe we could go this route (here are possible docstrings for both):
> 
>     Define abbrev for all modes that expands to word(s) before point.
>     Define word before point as abbrev for all modes, prompt for expansion.
> 
> The last is slightly long at 71 chars.

I don't see why these are better.  And we almost never mention the
prompt in the first line of a doc string, unless there's nothing more
important to say there (which isn't the case here).

> >> 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.
> 
> The sentence does not say "at the time of expansion" that would be clear.

Not explicitly, but that's implied quite clearly.  And given the
screen estate constraints, we cannot do much better, except in the
following parts of the doc string.

> Instead the sentence has a clause "and call HOOK" without an
> oxford comma, so it's not clear where the clause attaches to.

I won't object to adding a comma.  But I'm not sure it is needed,
since "expand and call" both allude to the abbrev.

> >>   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 wasn't clear on the conventions of including optional
> arguments in the first line of a docstring.  The existing
> string includes the optional HOOK but not PROPS.  The HOOK
> is optional and in Emacs itself only used by mail
> abbrevs. My choice would be to leave HOOK out of the first
> line.  But if it must be in there, how about:
> 
>     In TABLE, define an ABBREV, its EXPANSION, and optionally its HOOK.

The convention is that we don't have to mention optional arguments,
but we can if that's possible and important.

> If you don't care for this, then I'd be fine with just
> changing the argument NAME to ABBREV so the simplest change
> would be:
> 
>     Define an abbrev in TABLE named ABBREV, to expand to EXPANSION and call 
> HOOK.

Why not

  Define ABBREV in TABLE, to expand into EXPANSION and call HOOK.

?