From: Howard Melman <hmelman@gmail.com>
To: Eli Zaretskii <eliz@gnu.org>
Cc: 55527@debbugs.gnu.org
Subject: bug#55527: 28.1; Clearer abbrev docstrings
Date: Fri, 20 May 2022 13:03:43 -0400 [thread overview]
Message-ID: <27EF500E-25FC-4079-AA2F-66A8B3CA95B5@gmail.com> (raw)
In-Reply-To: <83leuw9ovm.fsf@gnu.org>
> 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
next prev parent reply other threads:[~2022-05-20 17:03 UTC|newest]
Thread overview: 18+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-05-19 18:32 bug#55527: 28.1; Clearer abbrev docstrings Howard Melman
2022-05-19 18:52 ` Eli Zaretskii
2022-05-19 19:30 ` Howard Melman
2022-05-19 19:46 ` Eli Zaretskii
2022-05-19 20:38 ` Howard Melman
2022-05-20 5:48 ` Eli Zaretskii
2022-05-20 13:35 ` Howard Melman
2022-05-20 15:59 ` Eli Zaretskii
2022-05-20 17:03 ` Howard Melman [this message]
2022-05-21 7:23 ` Eli Zaretskii
2022-05-21 13:41 ` Howard Melman
2022-05-21 14:09 ` Eli Zaretskii
2022-05-21 17:49 ` Howard Melman
2022-05-21 18:06 ` Eli Zaretskii
2022-05-21 18:26 ` Howard Melman
2022-05-21 18:46 ` Eli Zaretskii
2022-05-20 7:41 ` Juri Linkov
2022-05-20 13:12 ` Howard Melman
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=27EF500E-25FC-4079-AA2F-66A8B3CA95B5@gmail.com \
--to=hmelman@gmail.com \
--cc=55527@debbugs.gnu.org \
--cc=eliz@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).