bug#55527: 28.1; Clearer abbrev docstrings

[Howard Melman]

> On May 20, 2022, at 11:59 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> 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?

It's relevant to this bug report.

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

To the point above, these make it explict which part of the abbrev the
text before point will be used for.  

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

Given that just "abbrev" is somewhat ambiguous (and apparently not
just to me) it was a way to mention that the word before point isn't
used as the expansion.  I'm open to another construction that does this.

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

I'm fine with that, but the variables are not in the order they are called
which I know is usually desired.

Howard