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 13:03:43 -0400 Message-ID: <27EF500E-25FC-4079-AA2F-66A8B3CA95B5@gmail.com> References: <83bkvtcq38.fsf@gnu.org> <838rqxcnkk.fsf@gnu.org> <837d6gdaab.fsf@gnu.org> <83leuw9ovm.fsf@gnu.org> Mime-Version: 1.0 (Mac OS X Mail 14.0 \(3654.120.0.1.13\)) Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="31755"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 55527@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Fri May 20 19:05:23 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 1ns640-0007wA-7s for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 20 May 2022 19:05:20 +0200 Original-Received: from localhost ([::1]:46554 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ns63y-0002k6-P8 for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 20 May 2022 13:05:18 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:56128) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ns63i-0002io-L7 for bug-gnu-emacs@gnu.org; Fri, 20 May 2022 13:05:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:46100) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1ns63i-0004C0-76 for bug-gnu-emacs@gnu.org; Fri, 20 May 2022 13:05:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1ns63i-0000Po-2o for bug-gnu-emacs@gnu.org; Fri, 20 May 2022 13:05:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Howard Melman Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 20 May 2022 17:05: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.16530662441518 (code B ref 55527); Fri, 20 May 2022 17:05:02 +0000 Original-Received: (at 55527) by debbugs.gnu.org; 20 May 2022 17:04:04 +0000 Original-Received: from localhost ([127.0.0.1]:39997 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ns62k-0000OP-NM for submit@debbugs.gnu.org; Fri, 20 May 2022 13:04:03 -0400 Original-Received: from mail-qt1-f170.google.com ([209.85.160.170]:46005) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ns62Y-0000Ng-F4 for 55527@debbugs.gnu.org; Fri, 20 May 2022 13:04:02 -0400 Original-Received: by mail-qt1-f170.google.com with SMTP id v6so4319804qtx.12 for <55527@debbugs.gnu.org>; Fri, 20 May 2022 10:03:50 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=mime-version:subject:from:in-reply-to:date:cc :content-transfer-encoding:message-id:references:to; bh=JlZubaeVZzu/abyeIIA6vGVvj223kQ3vzCrVUEEwaBw=; b=CtFAyXg1db4D7fc+17sPa134BFAT2kEsvkxwqP3E619xx2nhPDDF0XsOm9cC/Yhn7Z tmUDT49LKPmmVqyxbtQ+iI0F97Iio+ljsnLbW7dNFEkh8w/gdmbI9TmdJx1Yn/CIfTKC s/LynZlh8vyWniWEKSg6TZQ+Wm42ZLpx+Dfcm9eP2PkrUIjpM4MuPjU4zGhH6rJaE4Kk PiWIzbHZQ4x0YHmp9/r4flRDu8nrHMuyLLSbbJEazTnnSuh+USdNTLj2Td+6mq45IV8C dTjpMzrcHrj2vvTN77XdEy2kvlsJqBBzxlyoVIfLg3IqVknQSICUoVjzaBYoTyzluNGz opiA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:mime-version:subject:from:in-reply-to:date:cc :content-transfer-encoding:message-id:references:to; bh=JlZubaeVZzu/abyeIIA6vGVvj223kQ3vzCrVUEEwaBw=; b=FPmVr/5EiNNbGObrOy9/5xy948OjENYxb6Iotyn4+VU0q6NrOJVV1N3AjB4pAP9b1w p0lv2Qd7jsgQm4jFC3nP7rYGBiZ1Tst1UOISAtxlUq3LvS1jd+lmI9EdWKQMjg49+9wv QY8aKGdrgmq4hYgq62r0Zgifn0HXVQ2ExlrJrIH+tcvh0O9bscQoV4DiPkthF5ZNjTpl xKs+NbViLPibXLHRKH8ap6OO3rds+lTQgxNm4o8NGmP7kzIwyV0D7WJarPgQYM279tD/ rzYYeDSjyxxuai81uhows7LRY/hvx3XA72U2EUSwjcFoOHjpqfPakCRoTLjUmwp/aVdk ZOmA== X-Gm-Message-State: AOAM531d2YTlE9EsEQikl9Fy+U+zliEgh/bWmW1J/6mAcqLfUewjxgqh 2hOQKBBEqHP00iP5eafj+/3+wzIlKHY= X-Google-Smtp-Source: ABdhPJxsMetu9GzjGsio/AYQ/kgZN2eYRQuvF1E/pYPOq7XGoj//2e3CZzslevwvmlI0mZGnnNU2xg== X-Received: by 2002:ac8:4707:0:b0:2ed:b56:5531 with SMTP id f7-20020ac84707000000b002ed0b565531mr8309323qtp.148.1653066224727; Fri, 20 May 2022 10:03:44 -0700 (PDT) Original-Received: from smtpclient.apple (pool-108-26-204-101.bstnma.fios.verizon.net. [108.26.204.101]) by smtp.gmail.com with ESMTPSA id d200-20020a3768d1000000b006a351e0eacdsm837575qkc.95.2022.05.20.10.03.43 (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Fri, 20 May 2022 10:03:44 -0700 (PDT) In-Reply-To: <83leuw9ovm.fsf@gnu.org> X-Mailer: Apple Mail (2.3654.120.0.1.13) 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:232783 Archived-At: > On May 20, 2022, at 11:59 AM, Eli Zaretskii wrote: >=20 >> From: Howard Melman >> Date: Fri, 20 May 2022 09:35:43 -0400 >>=20 >>>> Define last word before point as expansion of a global abbrev. >>>=20 >>> 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". >>=20 >> 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. >=20 > Is that relevant for the "global" issue to which I responded? It's relevant to this bug report. >=20 >> Maybe we could go this route (here are possible docstrings for both): >>=20 >> Define abbrev for all modes that expands to word(s) before point. >> Define word before point as abbrev for all modes, prompt for = expansion. >>=20 >> The last is slightly long at 71 chars. >=20 > I don't see why these are better. =20 To the point above, these make it explict which part of the abbrev the text before point will be used for. =20 > 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. >=20 >>>> Define an abbrev in TABLE named NAME, to expand to EXPANSION and = call HOOK. >>>>=20 >>>> which to me doesn't answer "by whom and when" >>>=20 >>> Yes, it does: the abbrev you define will call HOOK at the time of = the >>> expansion. That's what the sentence says. >>=20 >> The sentence does not say "at the time of expansion" that would be = clear. >=20 > 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. >=20 >> Instead the sentence has a clause "and call HOOK" without an >> oxford comma, so it's not clear where the clause attaches to. >=20 > 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. >=20 >>>> Define in TABLE an ABBREV and its EXPANSION and optionally its = HOOK. >>>=20 >>> "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. >>=20 >> 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: >>=20 >> In TABLE, define an ABBREV, its EXPANSION, and optionally its = HOOK. >=20 > The convention is that we don't have to mention optional arguments, > but we can if that's possible and important. >=20 >> 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: >>=20 >> Define an abbrev in TABLE named ABBREV, to expand to EXPANSION and = call HOOK. >=20 > Why not >=20 > 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