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: Fri, 20 May 2022 09:35:43 -0400 Message-ID: References: <83bkvtcq38.fsf@gnu.org> <838rqxcnkk.fsf@gnu.org> <837d6gdaab.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="40071"; 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:KN/QWU1JVbIGGKwS0lUuzbshUYs= Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Fri May 20 15:36:22 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 1ns2nl-000AGQ-5z for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 20 May 2022 15:36:21 +0200 Original-Received: from localhost ([::1]:56604 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ns2nj-0001WL-It for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 20 May 2022 09:36:19 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:41170) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ns2nV-0001WC-KN for bug-gnu-emacs@gnu.org; Fri, 20 May 2022 09:36:05 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:44114) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1ns2nS-0005PM-K6 for bug-gnu-emacs@gnu.org; Fri, 20 May 2022 09:36:05 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1ns2nS-0000lG-HZ for bug-gnu-emacs@gnu.org; Fri, 20 May 2022 09:36: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: Fri, 20 May 2022 13:36: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.16530537572914 (code B ref -1); Fri, 20 May 2022 13:36:02 +0000 Original-Received: (at submit) by debbugs.gnu.org; 20 May 2022 13:35:57 +0000 Original-Received: from localhost ([127.0.0.1]:38011 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ns2nN-0000kv-Cy for submit@debbugs.gnu.org; Fri, 20 May 2022 09:35:57 -0400 Original-Received: from lists.gnu.org ([209.51.188.17]:56696) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ns2nL-0000km-7U for submit@debbugs.gnu.org; Fri, 20 May 2022 09:35:55 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:41166) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ns2nL-0001Tx-1Q for bug-gnu-emacs@gnu.org; Fri, 20 May 2022 09:35:55 -0400 Original-Received: from ciao.gmane.io ([116.202.254.214]:45920) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ns2nJ-0005Oy-I2 for bug-gnu-emacs@gnu.org; Fri, 20 May 2022 09:35:54 -0400 Original-Received: from list by ciao.gmane.io with local (Exim 4.92) (envelope-from ) id 1ns2nH-0009Uz-0U for bug-gnu-emacs@gnu.org; Fri, 20 May 2022 15:35:51 +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:232768 Archived-At: Eli Zaretskii writes: >> From: Howard Melman >> >> > 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