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 14:32:44 -0400 Message-ID: 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="23488"; mail-complaints-to="usenet@ciao.gmane.io" To: 55527@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Thu May 19 20:33:41 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 1nrkxx-0005xN-5W for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 19 May 2022 20:33:41 +0200 Original-Received: from localhost ([::1]:33330 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nrkxv-0006Vv-Oq for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 19 May 2022 14:33:39 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:41276) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nrkxK-0006Sb-9k for bug-gnu-emacs@gnu.org; Thu, 19 May 2022 14:33:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:42672) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1nrkxK-0000dQ-0X for bug-gnu-emacs@gnu.org; Thu, 19 May 2022 14:33:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1nrkxJ-0001Fq-T1 for bug-gnu-emacs@gnu.org; Thu, 19 May 2022 14:33:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Howard Melman Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 19 May 2022 18:33:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 55527 X-GNU-PR-Package: emacs X-Debbugs-Original-To: GNU Emacs Original-Received: via spool by submit@debbugs.gnu.org id=B.16529851784810 (code B ref -1); Thu, 19 May 2022 18:33:01 +0000 Original-Received: (at submit) by debbugs.gnu.org; 19 May 2022 18:32:58 +0000 Original-Received: from localhost ([127.0.0.1]:36569 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nrkxG-0001FU-1k for submit@debbugs.gnu.org; Thu, 19 May 2022 14:32:58 -0400 Original-Received: from lists.gnu.org ([209.51.188.17]:33244) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nrkxD-0001FL-Vi for submit@debbugs.gnu.org; Thu, 19 May 2022 14:32:56 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:41244) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nrkxD-0006N5-Nz for bug-gnu-emacs@gnu.org; Thu, 19 May 2022 14:32:55 -0400 Original-Received: from mail-qt1-x82b.google.com ([2607:f8b0:4864:20::82b]:35789) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1nrkx8-0000bT-Ty for bug-gnu-emacs@gnu.org; Thu, 19 May 2022 14:32:55 -0400 Original-Received: by mail-qt1-x82b.google.com with SMTP id h9so868293qtx.2 for ; Thu, 19 May 2022 11:32:47 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:content-transfer-encoding:mime-version:subject:message-id:date :to; bh=FH8OWKtPYNuP2+1DY/jwvjRdHKf77hSrj/TgIlzOWeo=; b=C+ULzQ8hOt5Ni+Op+rRq/12mus3Ufmrul2fBf5RURpQ/VgqQjOeEfeNXAMRwFvx0I4 NTjHXs47rTixKaQAGEukvO2zflZRSoWuWjLn2Jz2iWoEDyEiJ9dHttZTOS55RdYZSW/Q b6R1En5gdvRELZktGmVPjWV6cNmeDc7ZuQfvsv19CP67ATW5ajq+RvF+djRdK9uNefkl tLwRNa0gcYgqgJkStwgVLnpcra9zLVcEwN41db8GAd/tqGS5JxZIYg9bkwVedi3rH+Sw E860V+khXe1/X1yKerqnIG3B7R9vKVddW5rHzlEeYXjbAPgxCSRkcEz7A70JCF7krq0H s2Qg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:content-transfer-encoding:mime-version :subject:message-id:date:to; bh=FH8OWKtPYNuP2+1DY/jwvjRdHKf77hSrj/TgIlzOWeo=; b=BACOCoLHj0kLsePYJnzWrT29dsrEjc69osAyq4TuyP29mPEY+XZ1UQqcLLRtBRizjs EVFQdG7wwQwMU7UmPC0OzQdJoWDY8ei4o8SQiUwOQUNmYQ6gYKy0nVuA35Fie9OUbQrM II5+c+dRJsTDOnYu9nC7LoqiDRpCJ5q7dStjk/MniGvbMfiBhIWtRabGKmK4JuA4FPh3 nHiZFNtuF+dpMs1drD5xlhmfw0CJWnJ86eXS3KLpU+h9ALvxZtY41A0AC366TdogDNZT N5P4e8MHRsDnPZ6K5EHBO67IEDSIukSwmSwxUEoer+bHIBmC9LGk810EzuFRsiesNAO7 cptg== X-Gm-Message-State: AOAM531j9+utojk9F0JydnHTzmfgS4VGgrOjNdGLT++Mz26R2Rqc/yCq LXHYWFgccAXhtERWjSxEKwfBcBAeQQ4= X-Google-Smtp-Source: ABdhPJzxUGXGHzwB7g6hgMmF8Qyto7vM1uxLXfw/pyDlm5/5k3OMC4D7kP1jKU8HbWZvEfssGFnQFQ== X-Received: by 2002:ac8:590c:0:b0:2f3:e1b7:5d1d with SMTP id 12-20020ac8590c000000b002f3e1b75d1dmr5026526qty.191.1652985165927; Thu, 19 May 2022 11:32:45 -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 w4-20020a05622a134400b002f906fc8530sm1693305qtk.46.2022.05.19.11.32.44 for (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Thu, 19 May 2022 11:32:45 -0700 (PDT) X-Mailer: Apple Mail (2.3654.120.0.1.13) Received-SPF: pass client-ip=2607:f8b0:4864:20::82b; envelope-from=hmelman@gmail.com; helo=mail-qt1-x82b.google.com X-Spam_score_int: -16 X-Spam_score: -1.7 X-Spam_bar: - X-Spam_report: (-1.7 / 5.0 requ) BAYES_00=-1.9, DKIM_INVALID=0.1, DKIM_SIGNED=0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, 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:232660 Archived-At: When using abbrev commands I'm always confused by which=20 is the abbrev and which is the expansion. I think there are a=20 few reasons for this. I know that the manual defines "abbrev" as the short name, but given it's the package and feature name I also think of it as an overused term for the pairing of an abbreviation and its expansion. With this confusion some of the prompts and command names are easily read as ambiguous. (I'll talk about the global forms here but they all apply to the mode-specific forms too.) First off, I don't define abbrevs frequently enough to remember their bindings, so I usually use M-x. The names of the commands add-global-abbrev and inverse-add-global-abbrev also don't resolve the ambiguity, since all they say is one is the inverse of the other. I know these are very old commands, but a clearer alias of the latter could be one of: add-global-expansion add-global-abbrev-expansion add-global-expansion-of-abbrev I use marginalia so I see annotations when using M-x which include the first line of the commands' docstring. The first line of the docstrings for add-global-abbrev and inverse-add-global-abbrev don't help me too much. They are currently: Define global (all modes) abbrev for last word(s) before point. Define last word before point as a global (mode-independent) abbrev. and I find I have to think hard to resolve which is which. I think these would be clearer: Use word(s) before point as the expansion of a new global abbrev. Use word before point as the abbreviation of a new global abbrev. The latter could also be this (though it's 70 chars long): Define word before point as a global abbrev, prompt for its = expansion. FWIW I do wish the documentation used "abbreviation" when it refers to the abbrev so that "abbrev" could refer to the pair of "abbreviation" and "expansion" or to the feature name. Even if it did this occasionally I think it would help. Then, if I do pick one of the commands the prompts don't give me confidence I chose the right one. These are the interactive prompts for add-global-abbrev and inverse-add-global-abbrev: 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": (I'm not sure if "of" or "for" read better in either of the above). Or even better: Global abbrev to expand to "foo": Expand global abbrev "foo" to: Finally define-abbrev has an argument "name" that I find too generic and a docstring first line I find awkward. Perhaps change this: (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. (and of course the two uses of the variable name in the function which I think will read much clearer.) Howard