bug#55527: 28.1; Clearer abbrev docstrings

[Howard Melman <hmelman@gmail.com>]

Eli Zaretskii <eliz@gnu.org> writes:

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

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.

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.

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

The sentence does not say "at the time of expansion" that would be clear.
Instead the sentence has a clause "and call HOOK" without an
oxford comma, so it's not clear where the clause attaches to.  It's also 75
chars long.

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

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.

Though now it's 77 chars, up from 75.

-- 

Howard