From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#55527: 28.1; Clearer abbrev docstrings Date: Fri, 20 May 2022 18:59:09 +0300 Message-ID: <83leuw9ovm.fsf@gnu.org> References: <83bkvtcq38.fsf@gnu.org> <838rqxcnkk.fsf@gnu.org> <837d6gdaab.fsf@gnu.org> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="18999"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 55527@debbugs.gnu.org To: Howard Melman Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Fri May 20 18:01:50 2022 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1ns54X-0004o4-Fa for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 20 May 2022 18:01:49 +0200 Original-Received: from localhost ([::1]:38648 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ns54V-00075A-QC for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 20 May 2022 12:01:47 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:41318) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ns52o-00074z-GB for bug-gnu-emacs@gnu.org; Fri, 20 May 2022 12:00:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:46055) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1ns52o-0002Ge-5H for bug-gnu-emacs@gnu.org; Fri, 20 May 2022 12:00:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1ns52o-00050X-37 for bug-gnu-emacs@gnu.org; Fri, 20 May 2022 12:00:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 20 May 2022 16:00:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 55527 X-GNU-PR-Package: emacs Original-Received: via spool by 55527-submit@debbugs.gnu.org id=B55527.165306236019161 (code B ref 55527); Fri, 20 May 2022 16:00:02 +0000 Original-Received: (at 55527) by debbugs.gnu.org; 20 May 2022 15:59:20 +0000 Original-Received: from localhost ([127.0.0.1]:39952 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ns528-0004yy-2J for submit@debbugs.gnu.org; Fri, 20 May 2022 11:59:20 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:47852) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ns525-0004yi-7K for 55527@debbugs.gnu.org; Fri, 20 May 2022 11:59:18 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:56102) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ns51z-0002Bn-U5; Fri, 20 May 2022 11:59:11 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=KOkIK5qGMdkccje69vssPH0rp/LE+XrsmAXr+pmb2gg=; b=E99SeFFjyPj+ Z0O+jyIVM70ckkAk8NM3tkFsNL12asAZufhoBmTzhkuSZiyBseb4WfDlq7ylREqRa7KNTFYLWonG8 dn7T+TnqfjKBAbEpYOPGO7EvE78kctJ1wnU8hrAGzdPctkhJHJjjx+29tqeDQV8eROej1nLntRQfv pATtvexEeR+lhuZMd9ff4wh/3jJ3Z1Esao8+8OiNcq9FaDElCRSA5/AJGyNe2nD7gaHPsNMlWCPoG r4XPzJUE7guBS+F0aTVrQqMMMxASQK6sCNPGzZXHx6IA0IsoJrv1UyaoDxJG0UWpKodvCH+977s8/ GcGxEJMTgV+s52rMXCavFA==; Original-Received: from [87.69.77.57] (port=1825 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ns51z-0007qe-D2; Fri, 20 May 2022 11:59:11 -0400 In-Reply-To: (message from Howard Melman on Fri, 20 May 2022 09:35:43 -0400) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:232779 Archived-At: > From: Howard Melman > 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. ?