From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Howard Melman Newsgroups: gmane.emacs.bugs Subject: bug#55527: 28.1; Clearer abbrev docstrings Date: Thu, 19 May 2022 15:30:18 -0400 Message-ID: References: <83bkvtcq38.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="19389"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.1 (darwin) To: 55527@debbugs.gnu.org Cancel-Lock: sha1:bxPcM9cId+CHUN4aq2gmEG08WGA= Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Thu May 19 21:37:40 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 1nrlxs-0004uw-8W for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 19 May 2022 21:37:40 +0200 Original-Received: from localhost ([::1]:44052 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nrlxr-00020g-9z for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 19 May 2022 15:37:39 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:50864) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nrlrS-0008N1-MD for bug-gnu-emacs@gnu.org; Thu, 19 May 2022 15:31:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:42721) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1nrlrS-0000HS-B2 for bug-gnu-emacs@gnu.org; Thu, 19 May 2022 15:31:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1nrlrS-0002jv-81 for bug-gnu-emacs@gnu.org; Thu, 19 May 2022 15:31:02 -0400 X-Loop: help-debbugs@gnu.org In-Reply-To: Resent-From: Howard Melman Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 19 May 2022 19:31:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 55527 X-GNU-PR-Package: emacs X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.165298863610495 (code B ref -1); Thu, 19 May 2022 19:31:02 +0000 Original-Received: (at submit) by debbugs.gnu.org; 19 May 2022 19:30:36 +0000 Original-Received: from localhost ([127.0.0.1]:36618 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nrlr1-0002jD-Qr for submit@debbugs.gnu.org; Thu, 19 May 2022 15:30:36 -0400 Original-Received: from lists.gnu.org ([209.51.188.17]:58466) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nrlqz-0002j5-RQ for submit@debbugs.gnu.org; Thu, 19 May 2022 15:30:34 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:50776) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nrlqz-0007or-GP for bug-gnu-emacs@gnu.org; Thu, 19 May 2022 15:30:33 -0400 Original-Received: from ciao.gmane.io ([116.202.254.214]:58518) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nrlqx-0000EK-Nw for bug-gnu-emacs@gnu.org; Thu, 19 May 2022 15:30:33 -0400 Original-Received: from list by ciao.gmane.io with local (Exim 4.92) (envelope-from ) id 1nrlqr-0005hs-SK for bug-gnu-emacs@gnu.org; Thu, 19 May 2022 21:30:25 +0200 X-Injected-Via-Gmane: http://gmane.org/ Received-SPF: pass client-ip=116.202.254.214; envelope-from=geb-bug-gnu-emacs@m.gmane-mx.org; helo=ciao.gmane.io X-Spam_score_int: 5 X-Spam_score: 0.5 X-Spam_bar: / X-Spam_report: (0.5 / 5.0 requ) BAYES_00=-1.9, DKIM_ADSP_CUSTOM_MED=0.001, FORGED_GMAIL_RCVD=1, FREEMAIL_FORGED_FROMDOMAIN=0.249, FREEMAIL_FROM=0.001, HEADER_FROM_DIFFERENT_DOMAINS=0.249, NML_ADSP_CUSTOM_MED=0.9, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=no autolearn_force=no X-Spam_action: no action 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:232664 Archived-At: Eli Zaretskii writes: >> From: Howard Melman >> Use word(s) before point as the expansion of a new global abbrev. > > "Use" is ambiguous, because it may be interpreted as "expand it now". > "Define" is better. So I would suggest > > Define a global abbrev that expands into word(s) preceding point. I think that's good. >> Use word before point as the abbreviation of a new global abbrev. > > "Abbreviation of a new abbrev" is confusing. I don't actually > understand what's wrong with the original one, viz.: > > Define last word before point as a global (mode-independent) abbrev. Because I'm not sure if the word will be used as the abbrev or the expansion. >> Define word before point as a global abbrev, prompt for its expansion. The above makes it clear, what do you think of it? >> Global abbrev for "foo": >> Global expansion for "foo": >> >> The latter is fine but the first confuses me (particularly >> when defining one word expansions), I think these would be >> clearer as: >> >> Global abbrev for expansion "foo": >> Global expansion of abbrev "foo": > > Is that really more clear? I think so, because both make it clear what "foo" will be used for. > I would say > > Global abbrev that expands into "foo": > Expansion for a global abbrev "foo": Those would be fine with me. > But I'm not sure we can make these prompts so much longer than the > original ones without overflowing the minibuffer into a second line, > which is a disadvantage. I tend to use very short abbrevs that expand into longer words, so it wouldn't be a problem for me. For those that expand them to something longer, these aren't that much longer prompts so the window they would break (expansions long enough to break but short enough not be broken before) doesn't seem large to me. >> (defun define-abbrev (table name expansion &optional hook &rest props) >> "Define an abbrev in TABLE named NAME, to expand to EXPANSION and call HOOK. >> >> to this: >> >> (defun define-abbrev (table abbrev expansion &optional hook &rest props) >> "Define in TABLE an ABBREV and its EXPANSION and optionally a HOOK. > > This loses the explanation of what is HOOK, and is also a very awkward > sentence that I think will be hard on non-native English > speakers. I'm not sure that "call HOOK" is an "explanation". I already assumed a "hook" would be called and I was confused when it would be called. I think mine makes it slightly clearer that it's associated with the persisted definition rather than called when the define-abbrev is called. And while I agree "Define in TABLE" is a little (not very) awkward, I think it's less awkard than the original, where NAME could be the name of the abbrev or of the TABLE. Also the original was 75 chars long and mine fits in the recommendated 67 character length. Maybe someone has a better suggestion, but I think changing "name" to "abbrev" is worth doing. Also I think the docstring should say define-abbrev returns "name" (hopefully changed to "abbrev"). Howard