From unknown Sun Jun 22 03:57:07 2025 X-Loop: help-debbugs@gnu.org Subject: bug#55527: 28.1; Clearer abbrev docstrings 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-GNU-PR-Keywords: To: 55527@debbugs.gnu.org X-Debbugs-Original-To: GNU Emacs Received: via spool by submit@debbugs.gnu.org id=B.16529851784810 (code B ref -1); Thu, 19 May 2022 18:33:01 +0000 Received: (at submit) by debbugs.gnu.org; 19 May 2022 18:32:58 +0000 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 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 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 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 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) 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) From: Howard Melman Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable Mime-Version: 1.0 (Mac OS X Mail 14.0 \(3654.120.0.1.13\)) Message-Id: Date: Thu, 19 May 2022 14:32:44 -0400 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-Spam-Score: -1.3 (-) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.3 (--) 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 From unknown Sun Jun 22 03:57:07 2025 X-Loop: help-debbugs@gnu.org Subject: bug#55527: 28.1; Clearer abbrev docstrings Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 19 May 2022 18:53:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 55527 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Howard Melman Cc: 55527@debbugs.gnu.org Received: via spool by 55527-submit@debbugs.gnu.org id=B55527.16529863606811 (code B ref 55527); Thu, 19 May 2022 18:53:01 +0000 Received: (at 55527) by debbugs.gnu.org; 19 May 2022 18:52:40 +0000 Received: from localhost ([127.0.0.1]:36586 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nrlGK-0001lm-34 for submit@debbugs.gnu.org; Thu, 19 May 2022 14:52:40 -0400 Received: from eggs.gnu.org ([209.51.188.92]:51050) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nrlGI-0001lY-Jd for 55527@debbugs.gnu.org; Thu, 19 May 2022 14:52:39 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:33860) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nrlGD-0003PT-AC; Thu, 19 May 2022 14:52:33 -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=YR8pPYDTENhg5sOrBtC2TJWgg2BAvrYg/8LeXpsOD4o=; b=jWKW6BJykEus bUMdl1vkiDk+nc9EGgXg3m/kdxf8uXLRO3FhbvmRJnDiQ09cuJQyDlt8VMRET3EeteVDEGEWOioOC Z4nUdgIljISdW/sZWzg3aCDw7q5Ytf3AKGMWf0m2vQkvt8UR9m2MM6Ys7S1pv9rSqWcJ/KgM4jWtl Mo99ikOCbF7cVQEkpv4AE+73Q0Zdk/myodSDKbKHbwaNUtcAvHDp+UwyzOaGuGleIOXIvG6/Rx9bk NexEpUThw05oPyyjpAoqCw3LYVRBYtAdZnfw5wQs3W8dzXj0hyGDcgVS/nF6unnXNf1G8LvcRwL40 hrYaNY8vNhTFKJVKWDXVFQ==; Received: from [87.69.77.57] (port=3702 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 1nrlGC-0008UJ-P4; Thu, 19 May 2022 14:52:33 -0400 Date: Thu, 19 May 2022 21:52:27 +0300 Message-Id: <83bkvtcq38.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: (message from Howard Melman on Thu, 19 May 2022 14:32:44 -0400) References: X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Howard Melman > Date: Thu, 19 May 2022 14:32:44 -0400 > > 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" 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. > 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. > 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. That'd be counter-productive, because it will cause these doc strings become longer and more confusing. > 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 would say Global abbrev that expands into "foo": Expansion for a global abbrev "foo": 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. > (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. From unknown Sun Jun 22 03:57:07 2025 X-Loop: help-debbugs@gnu.org Subject: bug#55527: 28.1; Clearer abbrev docstrings 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-GNU-PR-Keywords: To: 55527@debbugs.gnu.org X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.165298863610495 (code B ref -1); Thu, 19 May 2022 19:31:02 +0000 Received: (at submit) by debbugs.gnu.org; 19 May 2022 19:30:36 +0000 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 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 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 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 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/ From: Howard Melman Date: Thu, 19 May 2022 15:30:18 -0400 Message-ID: References: <83bkvtcq38.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.1 (darwin) Cancel-Lock: sha1:bxPcM9cId+CHUN4aq2gmEG08WGA= 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-Spam-Score: 0.1 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.9 (/) 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 From unknown Sun Jun 22 03:57:07 2025 X-Loop: help-debbugs@gnu.org Subject: bug#55527: 28.1; Clearer abbrev docstrings Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 19 May 2022 19:48:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 55527 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Howard Melman Cc: 55527@debbugs.gnu.org Received: via spool by 55527-submit@debbugs.gnu.org id=B55527.165298962212053 (code B ref 55527); Thu, 19 May 2022 19:48:01 +0000 Received: (at 55527) by debbugs.gnu.org; 19 May 2022 19:47:02 +0000 Received: from localhost ([127.0.0.1]:36650 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nrm6w-00038G-88 for submit@debbugs.gnu.org; Thu, 19 May 2022 15:47:02 -0400 Received: from eggs.gnu.org ([209.51.188.92]:60086) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nrm6t-00037m-Sb for 55527@debbugs.gnu.org; Thu, 19 May 2022 15:47:00 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:34748) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nrm6o-0002NU-FA; Thu, 19 May 2022 15:46:54 -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=2SXDzZjPUamarJc9OQ35Gz5nJUFrq9syX2ZUeEMObNk=; b=jc0KQ3wRpHgy 2nwAzXfad1SsUJTCmW/i+0vH62nQ53RLPejslSo733ZQyyH09zNAhP46ZgYQfM//1MiVUQzPYFnRv kVIJ9+DqC5cYzh6dP5nCzyWnp8IHjo+FAkxEH3W87l4Id2WuMfRVQ2oEfPRikKIptn+vevDXJbcOU 3zjPeOfksKzIzi0SjvAHnM9IjjOE/r0Ei1zdpYSRGZ191Mx7WVHTXGM+EYv6sLNWjN3Ul8meFd/lX 6f72z555CaYZ6JCtPYgKAvMlHsBXNAqTuV7tXpYIn/XBipu33WvX3lne4OlQC/uG5wLsdGsJ409IY MPZfLX7xnT5XAZh8lahiww==; Received: from [87.69.77.57] (port=3057 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 1nrm6n-0002Qa-VC; Thu, 19 May 2022 15:46:54 -0400 Date: Thu, 19 May 2022 22:46:51 +0300 Message-Id: <838rqxcnkk.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: (message from Howard Melman on Thu, 19 May 2022 15:30:18 -0400) References: <83bkvtcq38.fsf@gnu.org> X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Howard Melman > Date: Thu, 19 May 2022 15:30:18 -0400 > > > 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. 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 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. The problem in the first prompt is with "foo": it could be arbitrarily long. And in the second prompt you are supposed to type the expansion, which again can be long. > >> (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. It will be called, but by whom and when? From unknown Sun Jun 22 03:57:07 2025 X-Loop: help-debbugs@gnu.org Subject: bug#55527: 28.1; Clearer abbrev docstrings In-Reply-To: Resent-From: Howard Melman Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 19 May 2022 20:39:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 55527 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: 55527@debbugs.gnu.org X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.165299273916916 (code B ref -1); Thu, 19 May 2022 20:39:02 +0000 Received: (at submit) by debbugs.gnu.org; 19 May 2022 20:38:59 +0000 Received: from localhost ([127.0.0.1]:36684 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nrmvC-0004Om-PW for submit@debbugs.gnu.org; Thu, 19 May 2022 16:38:59 -0400 Received: from lists.gnu.org ([209.51.188.17]:60558) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nrmvB-0004Of-Lu for submit@debbugs.gnu.org; Thu, 19 May 2022 16:38:58 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:33114) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nrmvA-0005CQ-M2 for bug-gnu-emacs@gnu.org; Thu, 19 May 2022 16:38:57 -0400 Received: from ciao.gmane.io ([116.202.254.214]:44904) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nrmv8-0000rq-HB for bug-gnu-emacs@gnu.org; Thu, 19 May 2022 16:38:55 -0400 Received: from list by ciao.gmane.io with local (Exim 4.92) (envelope-from ) id 1nrmv6-0008hR-Hh for bug-gnu-emacs@gnu.org; Thu, 19 May 2022 22:38:52 +0200 X-Injected-Via-Gmane: http://gmane.org/ From: Howard Melman Date: Thu, 19 May 2022 16:38:42 -0400 Message-ID: References: <83bkvtcq38.fsf@gnu.org> <838rqxcnkk.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.1 (darwin) Cancel-Lock: sha1:0lcbj2zbpscfb7voQap/zv2Vg4Q= 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-Spam-Score: 0.1 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.9 (/) Eli Zaretskii writes: >> From: Howard Melman >> Date: Thu, 19 May 2022 15:30:18 -0400 >> >> > 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. > > 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. >> > 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. > > The problem in the first prompt is with "foo": it could be arbitrarily > long. And in the second prompt you are supposed to type the > expansion, which again can be long. Yes but I'm adding about 10 characters to the prompt, so once you get to "arbitrarily long", 10 characters only affects so many of them :) >> >> (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. > > 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" and I think is actually less clear than my rewording. Perhaps better is: Define in TABLE an ABBREV and its EXPANSION and optionally its HOOK. I don't think it's at all obvious how the original clauses relate to each other (thankfully the full docstring is much clearer) but as you brought up non-native english speakers I would think the original is also difficult for them. -- Howard From unknown Sun Jun 22 03:57:07 2025 X-Loop: help-debbugs@gnu.org Subject: bug#55527: 28.1; Clearer abbrev docstrings Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 20 May 2022 05:49:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 55527 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Howard Melman Cc: 55527@debbugs.gnu.org Received: via spool by 55527-submit@debbugs.gnu.org id=B55527.165302571817276 (code B ref 55527); Fri, 20 May 2022 05:49:01 +0000 Received: (at 55527) by debbugs.gnu.org; 20 May 2022 05:48:38 +0000 Received: from localhost ([127.0.0.1]:37290 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nrvV8-0004Ua-GE for submit@debbugs.gnu.org; Fri, 20 May 2022 01:48:38 -0400 Received: from eggs.gnu.org ([209.51.188.92]:49278) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nrvV6-0004UM-Qz for 55527@debbugs.gnu.org; Fri, 20 May 2022 01:48:37 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:49058) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nrvV1-0007Nf-Gq; Fri, 20 May 2022 01:48:31 -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=Z0uFCuiVbA6NkaqNVD1G/e5BqXsKEbHkFS2od2v8Boo=; b=a1XmtDaBZ36R h2KOOVlSPxhHFGF8K7nekHPMkpCKeEgRRGJO/ocv8mC8xILv0n+qnMb3ocIkw8ZJ+zZTwSdOVIYNq czgIjDv+ofxsegtLMBPOSLMVXJOvfToIOcpmtuMpovy9u9xXfhpoINUFZ9Z2apatfiKwfWJDTm4Gq 2wb4oSORqR7Gsup8lPBLwRU9f33zjBsJNoRQPruBQ+uEwr2hOKjMwTEGPCNxeKkkQu8EAOLNfSKnk sLy5O4SP51iV+Ij39hUjEmKi02jao0FYtSq+xdEIY4425FGIXMBv4vQw4gnCDQBwx2ADUdBbWD9NC xY/e6YnIKJyz+vIG8dwpEw==; Received: from [87.69.77.57] (port=3903 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 1nrvV0-0005az-HH; Fri, 20 May 2022 01:48:31 -0400 Date: Fri, 20 May 2022 08:48:28 +0300 Message-Id: <837d6gdaab.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: (message from Howard Melman on Thu, 19 May 2022 16:38:42 -0400) References: <83bkvtcq38.fsf@gnu.org> <838rqxcnkk.fsf@gnu.org> X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Howard Melman > Date: Thu, 19 May 2022 16:38:42 -0400 > > > 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". > > 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. > 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 don't think it's at all obvious how the original clauses > relate to each other (thankfully the full docstring is much > clearer) but as you brought up non-native english speakers I > would think the original is also difficult for them. The comparison is always relative, not absolute. And if the full doc string makes things clear, it's fine. From unknown Sun Jun 22 03:57:07 2025 X-Loop: help-debbugs@gnu.org Subject: bug#55527: 28.1; Clearer abbrev docstrings Resent-From: Juri Linkov Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 20 May 2022 07:52:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 55527 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Howard Melman Cc: 55527@debbugs.gnu.org Received: via spool by 55527-submit@debbugs.gnu.org id=B55527.16530330887247 (code B ref 55527); Fri, 20 May 2022 07:52:01 +0000 Received: (at 55527) by debbugs.gnu.org; 20 May 2022 07:51:28 +0000 Received: from localhost ([127.0.0.1]:37442 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nrxQ0-0001sp-Ck for submit@debbugs.gnu.org; Fri, 20 May 2022 03:51:28 -0400 Received: from relay1-d.mail.gandi.net ([217.70.183.193]:36085) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nrxPx-0001sZ-Lg for 55527@debbugs.gnu.org; Fri, 20 May 2022 03:51:26 -0400 Received: (Authenticated sender: juri@linkov.net) by mail.gandi.net (Postfix) with ESMTPSA id 8416624000E; Fri, 20 May 2022 07:51:17 +0000 (UTC) From: Juri Linkov Organization: LINKOV.NET References: Date: Fri, 20 May 2022 10:41:56 +0300 In-Reply-To: (Howard Melman's message of "Thu, 19 May 2022 14:32:44 -0400") Message-ID: <86ee0ohcqj.fsf@mail.linkov.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (x86_64-pc-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -0.7 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.7 (-) > When using abbrev commands I'm always confused by which > is the abbrev and which is the expansion. I think there are a > few reasons for this. The unhelpful abbrev docstrings and prompts is a known problem. Recently I tried to ameliorate this problem by adding these new sections to the docstrings: See also ‘inverse-add-global-abbrev’, which performs the opposite task: if the abbrev text is already in the buffer, use this command to define an abbrev by specifying the expansion in the minibuffer. and See also ‘add-global-abbrev’, which performs the opposite task: if the expansion is already in the buffer, use this command to define an abbrev by specifying the abbrev in the minibuffer. So every time I use this feature, I have to consult these parts of docstrings to recall what these commands do. > 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. > > [...] > > Global abbrev for expansion "foo": > Global expansion of abbrev "foo": Thanks, these and other such changes would be much of help. From unknown Sun Jun 22 03:57:07 2025 X-Loop: help-debbugs@gnu.org Subject: bug#55527: 28.1; Clearer abbrev docstrings 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:13:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 55527 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: 55527@debbugs.gnu.org X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.1653052357513 (code B ref -1); Fri, 20 May 2022 13:13:01 +0000 Received: (at submit) by debbugs.gnu.org; 20 May 2022 13:12:37 +0000 Received: from localhost ([127.0.0.1]:37972 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ns2Qm-00008D-Rt for submit@debbugs.gnu.org; Fri, 20 May 2022 09:12:37 -0400 Received: from lists.gnu.org ([209.51.188.17]:39284) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ns2Qk-000085-JJ for submit@debbugs.gnu.org; Fri, 20 May 2022 09:12:34 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:36940) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ns2Qi-0005BC-Bz for bug-gnu-emacs@gnu.org; Fri, 20 May 2022 09:12:32 -0400 Received: from ciao.gmane.io ([116.202.254.214]:43634) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ns2Qg-0001PO-Ln for bug-gnu-emacs@gnu.org; Fri, 20 May 2022 09:12:32 -0400 Received: from list by ciao.gmane.io with local (Exim 4.92) (envelope-from ) id 1ns2Qd-0009pF-Jr for bug-gnu-emacs@gnu.org; Fri, 20 May 2022 15:12:27 +0200 X-Injected-Via-Gmane: http://gmane.org/ From: Howard Melman Date: Fri, 20 May 2022 09:12:20 -0400 Message-ID: References: <86ee0ohcqj.fsf@mail.linkov.net> Mime-Version: 1.0 Content-Type: text/plain User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.1 (darwin) Cancel-Lock: sha1:ads1Qd01Ly7q4Bkpd7YhVA5eM0Q= 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-Spam-Score: 0.1 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.9 (/) Juri Linkov writes: > The unhelpful abbrev docstrings and prompts is a known problem. Thanks for saying so, I wasn't sure if I was the only one confused by them. > Recently I tried to ameliorate this problem by adding > these new sections to the docstrings: I saw these were added 9 months ago and they are indeed helpful, thanks. >> 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. >> >> [...] >> >> Global abbrev for expansion "foo": >> Global expansion of abbrev "foo": > > Thanks, these and other such changes would be much of help. Thanks for the confirmation. -- Howard From unknown Sun Jun 22 03:57:07 2025 X-Loop: help-debbugs@gnu.org Subject: bug#55527: 28.1; Clearer abbrev docstrings 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-GNU-PR-Keywords: To: 55527@debbugs.gnu.org X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.16530537572914 (code B ref -1); Fri, 20 May 2022 13:36:02 +0000 Received: (at submit) by debbugs.gnu.org; 20 May 2022 13:35:57 +0000 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 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 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 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 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/ From: Howard Melman 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 User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.1 (darwin) Cancel-Lock: sha1:KN/QWU1JVbIGGKwS0lUuzbshUYs= 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-Spam-Score: 0.1 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.9 (/) 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 From unknown Sun Jun 22 03:57:07 2025 X-Loop: help-debbugs@gnu.org Subject: bug#55527: 28.1; Clearer abbrev docstrings 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 X-GNU-PR-Keywords: To: Howard Melman Cc: 55527@debbugs.gnu.org Received: via spool by 55527-submit@debbugs.gnu.org id=B55527.165306236019161 (code B ref 55527); Fri, 20 May 2022 16:00:02 +0000 Received: (at 55527) by debbugs.gnu.org; 20 May 2022 15:59:20 +0000 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 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 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==; 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 Date: Fri, 20 May 2022 18:59:09 +0300 Message-Id: <83leuw9ovm.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: (message from Howard Melman on Fri, 20 May 2022 09:35:43 -0400) References: <83bkvtcq38.fsf@gnu.org> <838rqxcnkk.fsf@gnu.org> <837d6gdaab.fsf@gnu.org> X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > 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. ? From unknown Sun Jun 22 03:57:07 2025 X-Loop: help-debbugs@gnu.org Subject: bug#55527: 28.1; Clearer abbrev docstrings 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 X-GNU-PR-Keywords: To: Eli Zaretskii Cc: 55527@debbugs.gnu.org Received: via spool by 55527-submit@debbugs.gnu.org id=B55527.16530662441518 (code B ref 55527); Fri, 20 May 2022 17:05:02 +0000 Received: (at 55527) by debbugs.gnu.org; 20 May 2022 17:04:04 +0000 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 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 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) 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) Content-Type: text/plain; charset=us-ascii Mime-Version: 1.0 (Mac OS X Mail 14.0 \(3654.120.0.1.13\)) From: Howard Melman In-Reply-To: <83leuw9ovm.fsf@gnu.org> Date: Fri, 20 May 2022 13:03:43 -0400 Content-Transfer-Encoding: quoted-printable 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> X-Mailer: Apple Mail (2.3654.120.0.1.13) X-Spam-Score: -0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) > 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 From unknown Sun Jun 22 03:57:07 2025 X-Loop: help-debbugs@gnu.org Subject: bug#55527: 28.1; Clearer abbrev docstrings Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 21 May 2022 07:24:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 55527 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Howard Melman Cc: 55527@debbugs.gnu.org Received: via spool by 55527-submit@debbugs.gnu.org id=B55527.165311781423241 (code B ref 55527); Sat, 21 May 2022 07:24:02 +0000 Received: (at 55527) by debbugs.gnu.org; 21 May 2022 07:23:34 +0000 Received: from localhost ([127.0.0.1]:40603 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nsJSY-00062n-BZ for submit@debbugs.gnu.org; Sat, 21 May 2022 03:23:34 -0400 Received: from eggs.gnu.org ([209.51.188.92]:50802) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nsJSW-00062a-Ns for 55527@debbugs.gnu.org; Sat, 21 May 2022 03:23:33 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:48004) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nsJSR-0002Hv-F0; Sat, 21 May 2022 03:23:27 -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=wztRrGP4fGJc3e05LsU7Eu0DcwQv9ZUn2MY2tuEBdYI=; b=Pw4y5Js71moW g/LGsCKbyx7t5QW4l7S0GD1SaAg6Oio2gsZNxzSLNASY/7jp4hTOkUsoKp7EdvQNTP+0w1he7oOwk fVinp44tkM522+rfeKeQImnPjt8mZSaUrrcuPyV4LaGyWclpBVOyir4ulpm0B5bpHBiv3RmVezb2h DR91/QFpnHZO3mHKtbRHvwG+ECDPWEhvNLUzXBqg2csxMT5vSO7s+NzKY6Sl5NqUlnyWNoHljqL1v fwDvrfoj6Gd+U0r59rlwTG/1p7ocD1wmlEVGelKos4OR/AL2hfFVYuL9IEAPW8vcfeMk7YXRul9Ra IrNk2CM/53QzYnpYJDGNyA==; Received: from [87.69.77.57] (port=3716 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 1nsJSQ-0005xK-Ul; Sat, 21 May 2022 03:23:27 -0400 Date: Sat, 21 May 2022 10:23:22 +0300 Message-Id: <838rqv9wnp.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: <27EF500E-25FC-4079-AA2F-66A8B3CA95B5@gmail.com> (message from Howard Melman on Fri, 20 May 2022 13:03:43 -0400) References: <83bkvtcq38.fsf@gnu.org> <838rqxcnkk.fsf@gnu.org> <837d6gdaab.fsf@gnu.org> <83leuw9ovm.fsf@gnu.org> <27EF500E-25FC-4079-AA2F-66A8B3CA95B5@gmail.com> X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) I've now improved the doc strings and prompts, on the release branch, per this discussion. Any more issues, or can we close this? Thanks. From unknown Sun Jun 22 03:57:07 2025 X-Loop: help-debbugs@gnu.org Subject: bug#55527: 28.1; Clearer abbrev docstrings Resent-From: Howard Melman Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 21 May 2022 13:42:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 55527 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Eli Zaretskii Cc: 55527@debbugs.gnu.org Received: via spool by 55527-submit@debbugs.gnu.org id=B55527.165314051324024 (code B ref 55527); Sat, 21 May 2022 13:42:02 +0000 Received: (at 55527) by debbugs.gnu.org; 21 May 2022 13:41:53 +0000 Received: from localhost ([127.0.0.1]:41013 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nsPMf-0006FP-8I for submit@debbugs.gnu.org; Sat, 21 May 2022 09:41:53 -0400 Received: from mail-qk1-f182.google.com ([209.85.222.182]:41768) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nsPMb-0006F5-9v for 55527@debbugs.gnu.org; Sat, 21 May 2022 09:41:52 -0400 Received: by mail-qk1-f182.google.com with SMTP id 190so3180105qkj.8 for <55527@debbugs.gnu.org>; Sat, 21 May 2022 06:41:49 -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=estoQs+IRBY/8XLwZJUX2Zq2TOKUQivMTnId2d5wH/g=; b=jN6gb2hcGtAdMipOqrStLmk56EFpgPbDvwB2X89v0wao5i2HIUnB1uVAhhQStBsPfQ T9YkNXAg8WEl+fGLgzm31auSK58klKd5RsYii7a2+FlUtTScu+HQmnZjLNpb1XAAQv6H hiJzLDO/ijlXaY5PxfCGwPd47RpHfU1d+whhiD5MGAcYGK06Obvz4KfWCoeQZC+blfEn OdSjm2Rjk/naUrmLpreDvF6aNKF3i/Hp/h3/r7uQXxD/4E2t0nFAyC45+miX81PTvKNY 8A1GAtyhid8Ug7LU+uz9lFOgAFSOU43wstsC9dMjtyxsm30baRbEuREzVDcvadQaXoew tBYg== 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=estoQs+IRBY/8XLwZJUX2Zq2TOKUQivMTnId2d5wH/g=; b=xwZwzUm5DaTtFmaeiglyGWNvCwH+87dkEnhMioXbSDb4Itb/PhZoyO6xg0saiAlfk2 vi4KXMb3yy4qoENRi2xXVqupeiHv77qzC7wU/wQkxuPw6ND0Mv98ulMn/3NcoQHpU4+v NGAhUgVTMfCw+WKb1zMy9HFa5tzR3KGJ7zqrVmXhvTlpmBMz8QKwOgj3kO564lmcxUMi f7MsXZDH9t1SR50DFcri1HY9F4qMauAPf2xaS0biUKek3Fnz/IAR6rhQuYdNX0LRhWwa AOCtkRGSnontFaZR4o56Hff6bl+4KYX9Lw/6H39K0yykx3aCdj3fLXfYFzesqHQ3V1dN jQTQ== X-Gm-Message-State: AOAM530XAWDnD4nEF6McK6WGS0c/0+Z6binvym6vEtu+eLP4vLfxghxr 91EyJFZiO+uF8orbNJ+HSNE= X-Google-Smtp-Source: ABdhPJySMppLum2nnv4bWhHpBj/4WQ/X/JzSvOYLEY+v7Ec+2wxBIQ0a/QQOpdFZECOV2Qp8PTobAQ== X-Received: by 2002:a05:620a:120f:b0:6a3:696b:2be2 with SMTP id u15-20020a05620a120f00b006a3696b2be2mr1430485qkj.780.1653140503523; Sat, 21 May 2022 06:41:43 -0700 (PDT) Received: from smtpclient.apple (pool-108-26-204-101.bstnma.fios.verizon.net. [108.26.204.101]) by smtp.gmail.com with ESMTPSA id t184-20020a3791c1000000b0069fc13ce209sm1347214qkd.58.2022.05.21.06.41.42 (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Sat, 21 May 2022 06:41:42 -0700 (PDT) Content-Type: text/plain; charset=us-ascii Mime-Version: 1.0 (Mac OS X Mail 14.0 \(3654.120.0.1.13\)) From: Howard Melman In-Reply-To: <838rqv9wnp.fsf@gnu.org> Date: Sat, 21 May 2022 09:41:41 -0400 Content-Transfer-Encoding: quoted-printable Message-Id: <6DB8A7EA-325F-4E1D-8382-431581A07B95@gmail.com> References: <83bkvtcq38.fsf@gnu.org> <838rqxcnkk.fsf@gnu.org> <837d6gdaab.fsf@gnu.org> <83leuw9ovm.fsf@gnu.org> <27EF500E-25FC-4079-AA2F-66A8B3CA95B5@gmail.com> <838rqv9wnp.fsf@gnu.org> X-Mailer: Apple Mail (2.3654.120.0.1.13) X-Spam-Score: -0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) On May 21, 2022, at 3:23 AM, Eli Zaretskii wrote: >=20 > I've now improved the doc strings and prompts, on the release branch, > per this discussion. >=20 > Any more issues, or can we close this? I think the new prompts will be very helpful. I think the new use of "abbreviation" in the inverse- flavor of the commands will help. For the non-inverse commands I'd love to see the "word(s)" construction retained as it jumps out when skimming the docstring and is a bit more accurate. So how about: (defun add-mode-abbrev (arg) "Define a mode-specific abbrev which expands into the word(s) before = point. (defun add-global-abbrev (arg) "Define a global (all modes) abbrev which expands into word(s) before = point. Howard From unknown Sun Jun 22 03:57:07 2025 X-Loop: help-debbugs@gnu.org Subject: bug#55527: 28.1; Clearer abbrev docstrings Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 21 May 2022 14:11:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 55527 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Howard Melman Cc: 55527@debbugs.gnu.org Received: via spool by 55527-submit@debbugs.gnu.org id=B55527.16531422314679 (code B ref 55527); Sat, 21 May 2022 14:11:02 +0000 Received: (at 55527) by debbugs.gnu.org; 21 May 2022 14:10:31 +0000 Received: from localhost ([127.0.0.1]:42764 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nsPoM-0001DP-R8 for submit@debbugs.gnu.org; Sat, 21 May 2022 10:10:31 -0400 Received: from eggs.gnu.org ([209.51.188.92]:43042) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nsPoJ-0001D4-0b for 55527@debbugs.gnu.org; Sat, 21 May 2022 10:10:29 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:52778) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nsPoD-0004PP-QV; Sat, 21 May 2022 10:10:21 -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=hgYsgoTBd6Kq+3ZjDQVOf+tEc3L85dilF8R5pBAfBLA=; b=QYaJ1GCO5XPG g75ej5WrFFiJxB9kpSK/+OMWIiXbjZDNCuxa0rs5MU+Sx78maHEm1R1rlauaOcK5SH625Uk7XRw2e zjzJw6/Kz3FQp+WkgtjFJA16tb8sa+04f58Gbhvl2ASdCGyuOD36jymJ0xawJxVWC16v0OvZPMSMK QPxiAaymHI4Bkj13a/adSDhx4YXlZ18H3bvfuvLnOLs7Xhj+rOsPuA6pHkdIZyQp517iaw3xT+8+g c5G1I7xvHmhrGe8ko1krsDxsQ7iZyS0zvrG9CpTqH346PZ28H5LpFpVZ4vU/uiG6tWkLUg3AjkmAS /2dnutAgwV94SfgPPY2DDA==; Received: from [87.69.77.57] (port=1865 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 1nsPo2-0007wg-GU; Sat, 21 May 2022 10:10:20 -0400 Date: Sat, 21 May 2022 17:09:59 +0300 Message-Id: <83fsl37z9k.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: <6DB8A7EA-325F-4E1D-8382-431581A07B95@gmail.com> (message from Howard Melman on Sat, 21 May 2022 09:41:41 -0400) References: <83bkvtcq38.fsf@gnu.org> <838rqxcnkk.fsf@gnu.org> <837d6gdaab.fsf@gnu.org> <83leuw9ovm.fsf@gnu.org> <27EF500E-25FC-4079-AA2F-66A8B3CA95B5@gmail.com> <838rqv9wnp.fsf@gnu.org> <6DB8A7EA-325F-4E1D-8382-431581A07B95@gmail.com> X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Howard Melman > Date: Sat, 21 May 2022 09:41:41 -0400 > Cc: 55527@debbugs.gnu.org > > For the non-inverse commands I'd love to see the "word(s)" > construction retained as it jumps out when skimming the docstring and > is a bit more accurate. So how about: > > (defun add-mode-abbrev (arg) > "Define a mode-specific abbrev which expands into the word(s) before point. > > (defun add-global-abbrev (arg) > "Define a global (all modes) abbrev which expands into word(s) before point. This is IMO a tradeoff for the worse: it makes the first line less clear on behalf of including information that is non-essential. In many commands, we describe in the first line what the command does by default, and defer the description of what ARG does to the body of the doc string. A random example: (transpose-chars ARG) Interchange characters around point, moving forward one character. With prefix arg ARG, effect is to take character before point and drag it forward past ARG other characters (backward if ARG negative). add-mode-abbrev and add-global-abbrev are the main user-level entry points into this facility, so IMO it is much more important to have the first line be as self-explanatory as possible than to describe in it some optional features. After all, most users will invoke these commands through their key bindings, thus without any prefix arg. Moreover, some values of the prefix have the effect that isn't captured by saying "word(s)", and I see no reason to consider those effects less important than the effect of a positive ARG. So I'd prefer to keep the new doc strings as they are. From unknown Sun Jun 22 03:57:07 2025 X-Loop: help-debbugs@gnu.org Subject: bug#55527: 28.1; Clearer abbrev docstrings Resent-From: Howard Melman Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 21 May 2022 17:51:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 55527 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Eli Zaretskii Cc: 55527@debbugs.gnu.org Received: via spool by 55527-submit@debbugs.gnu.org id=B55527.16531554082353 (code B ref 55527); Sat, 21 May 2022 17:51:02 +0000 Received: (at 55527) by debbugs.gnu.org; 21 May 2022 17:50:08 +0000 Received: from localhost ([127.0.0.1]:42901 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nsTEl-0000bK-0N for submit@debbugs.gnu.org; Sat, 21 May 2022 13:50:08 -0400 Received: from mail-qk1-f179.google.com ([209.85.222.179]:44794) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nsTEj-0000b6-AQ for 55527@debbugs.gnu.org; Sat, 21 May 2022 13:49:57 -0400 Received: by mail-qk1-f179.google.com with SMTP id i68so8920416qke.11 for <55527@debbugs.gnu.org>; Sat, 21 May 2022 10:49:57 -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=FbC9WUmr3JVqdoHfR3wt691UuOF8mKY6zXgcVxM++oI=; b=o+gVRoB+u04pBoCSRMWleXPGTsSxvh5AR8eay15ctLO6z69cHyqVBZvHM2oTqvoqMM Qt386kHD5zI3wTrK7hRgkIy0QbQqD0961RfrtpAs/U/lT9z4AeQgxFf1Q7rTEoeRv6tg kH0qyjcq2B4CiYwqSZsQ4inDaUN3FQuzIYTuiXi+E6Or1z7dr6gaPzGm1pJyV6DIQNPH Ax0nQdK/3UGloyIHsU/dNgNmAkQph+chC6k1gQ6Z4b+HyBPeeOnWzsziGZdgXBdFufK8 /hPgurCA0ydYcKwTLYwROyuiS9dFFbtiV7VMMseVwZM0qMZYei2xAOHBVWml44RL9Nlj zf3w== 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=FbC9WUmr3JVqdoHfR3wt691UuOF8mKY6zXgcVxM++oI=; b=He5M6Ee8T0xC8ySGnpEnbQ0oyp4EJsR/ZjOem/3X9JBBTSawsn/7JjQrU/4Bvzpe30 9xloKPTuof8dp+kK/4ASOmcDGM1k+Ao1jk3QK7b8z3+ajuggEUQuGdgCql2NAoP1BU7R wh4C18Kt4dF9seTYJHa9MPoxLMmTEebS794uU632HqQUPMguk2Ru06k6joPwllFysHjQ TU4z22wp5gm5jz8vRM4CACro5JIIrrm4/jW8lYJbsDwOZGW78DShiRd+gh0hGZoary3S 3wD+SAZKVMcwVEFCogSIhiL1PVTTLzrOTDDNgcjmoOVEl056uYQL4dgfjbWa0sVIG6Uz gFkA== X-Gm-Message-State: AOAM533/Hs6MNMp4vJg0d/TDPCsNOc7DFOUr1yi+ty4pZ8gLTHd5D8m2 UAjMYdZjPh7cdsFZdLcmLTgFiD/67rQ= X-Google-Smtp-Source: ABdhPJy4zjoog2Wa9aUghouYcq9La7OWuKl/gkttiWBPTusYszedy25dEEaGdflVovj7VpL8kEfs1g== X-Received: by 2002:a37:5844:0:b0:69f:7ea7:2be0 with SMTP id m65-20020a375844000000b0069f7ea72be0mr9686114qkb.667.1653155391409; Sat, 21 May 2022 10:49:51 -0700 (PDT) Received: from smtpclient.apple (pool-108-26-204-101.bstnma.fios.verizon.net. [108.26.204.101]) by smtp.gmail.com with ESMTPSA id h20-20020ac846d4000000b002f39b99f6b1sm1573651qto.75.2022.05.21.10.49.50 (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Sat, 21 May 2022 10:49:50 -0700 (PDT) Content-Type: text/plain; charset=us-ascii Mime-Version: 1.0 (Mac OS X Mail 14.0 \(3654.120.0.1.13\)) From: Howard Melman In-Reply-To: <83fsl37z9k.fsf@gnu.org> Date: Sat, 21 May 2022 13:49:48 -0400 Content-Transfer-Encoding: quoted-printable Message-Id: <96FE2CC0-8A4C-4099-A3D5-5FDD351C739F@gmail.com> References: <83bkvtcq38.fsf@gnu.org> <838rqxcnkk.fsf@gnu.org> <837d6gdaab.fsf@gnu.org> <83leuw9ovm.fsf@gnu.org> <27EF500E-25FC-4079-AA2F-66A8B3CA95B5@gmail.com> <838rqv9wnp.fsf@gnu.org> <6DB8A7EA-325F-4E1D-8382-431581A07B95@gmail.com> <83fsl37z9k.fsf@gnu.org> X-Mailer: Apple Mail (2.3654.120.0.1.13) X-Spam-Score: -0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) On May 21, 2022, at 10:09 AM, Eli Zaretskii wrote: >=20 >> From: Howard Melman >> Date: Sat, 21 May 2022 09:41:41 -0400 >> Cc: 55527@debbugs.gnu.org >>=20 >> For the non-inverse commands I'd love to see the "word(s)" >> construction retained as it jumps out when skimming the docstring and >> is a bit more accurate. So how about: >>=20 >> (defun add-mode-abbrev (arg) >> "Define a mode-specific abbrev which expands into the word(s) before = point. >>=20 >> (defun add-global-abbrev (arg) >> "Define a global (all modes) abbrev which expands into word(s) = before point. >=20 > This is IMO a tradeoff for the worse: it makes the first line less > clear on behalf of including information that is non-essential. >=20 > In many commands, we describe in the first line what the command does > by default, and defer the description of what ARG does to the body of > the doc string. A random example: >=20 > (transpose-chars ARG) >=20 > Interchange characters around point, moving forward one character. > With prefix arg ARG, effect is to take character before point > and drag it forward past ARG other characters (backward if ARG = negative). The existing docstrings for these commands had "word(s)" in them and I don't think that's what made them unclear. I also think it's a common case to define an abbrev for a multi-word expansion. I count about 80 first line docstrings in Emacs lisp code that use a = "(s)" construct. =20 But looking at forward-word's docstring for inspiration, how about this: "Define a mode-specific abbrev which expands into ARG words before = point. "Define a global (all modes) abbrev which expands into ARG words = before point. I think using ARG as above includes the common case of an expansion being more than one word and defers the less common uses of a zero or negative arg to the docstring body. I think too that an ARG=20= of zero is unclear so the user would read the body. A negative ARG = would often reverse direction so perhaps it's unintuitive, but I think that's = the case if ARG is mentioned in the first line or not. Also, I see now that the inverse- versions of these command treat a=20 negative argument as reversing the direction to find the word to use as the abbreviation but the (old and new) docstrings fails to mention=20 this. I'm not sure if that's intentional or not (IMO it's an odd use = case). Howard From unknown Sun Jun 22 03:57:07 2025 X-Loop: help-debbugs@gnu.org Subject: bug#55527: 28.1; Clearer abbrev docstrings Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 21 May 2022 18:07:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 55527 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Howard Melman Cc: 55527@debbugs.gnu.org Received: via spool by 55527-submit@debbugs.gnu.org id=B55527.16531563903935 (code B ref 55527); Sat, 21 May 2022 18:07:02 +0000 Received: (at 55527) by debbugs.gnu.org; 21 May 2022 18:06:30 +0000 Received: from localhost ([127.0.0.1]:42914 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nsTUk-00011O-1s for submit@debbugs.gnu.org; Sat, 21 May 2022 14:06:30 -0400 Received: from eggs.gnu.org ([209.51.188.92]:45398) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nsTUf-00011A-Sv for 55527@debbugs.gnu.org; Sat, 21 May 2022 14:06:29 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:55142) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nsTUY-0002jN-Gr; Sat, 21 May 2022 14:06:18 -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=9VkppGqhp/kYv41lZdaFVXQr0CIhAieBmrbXvzqCmDA=; b=ApW3C5Jmnb8A ur7BUglYlCFL9G43BWvRAK3BGNPVbTOqbvhhSxobbLyrwuABxr1I6gA7FZLFIqMgAdNLyAMwXTctP P1iF0ZJ2KLaJhxypcmxJVVTJWElqbgOuMeSKqNfL8S4t3GdpBhTYSvUpNFmLQ6YfU1PlXX/LVbCEz mP3tbuy8Pm5cnOoXynMmq8yqbcnj/ot6FcbGG/pw01lLZXNp08DFRJ1FF0J/BM6gMWY5/XPPTYPUO STy4EiXuzjrNXGTj90CLP8MB6HmKIRMejic/+E25x8x73IX/m9CS/U6AugWXgkXWxB1k+cvFfDWqg DoMwAyAsKYYydS2ZItCYzQ==; Received: from [87.69.77.57] (port=4451 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 1nsTUY-0000sC-0D; Sat, 21 May 2022 14:06:18 -0400 Date: Sat, 21 May 2022 21:06:01 +0300 Message-Id: <83bkvq92wm.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: <96FE2CC0-8A4C-4099-A3D5-5FDD351C739F@gmail.com> (message from Howard Melman on Sat, 21 May 2022 13:49:48 -0400) References: <83bkvtcq38.fsf@gnu.org> <838rqxcnkk.fsf@gnu.org> <837d6gdaab.fsf@gnu.org> <83leuw9ovm.fsf@gnu.org> <27EF500E-25FC-4079-AA2F-66A8B3CA95B5@gmail.com> <838rqv9wnp.fsf@gnu.org> <6DB8A7EA-325F-4E1D-8382-431581A07B95@gmail.com> <83fsl37z9k.fsf@gnu.org> <96FE2CC0-8A4C-4099-A3D5-5FDD351C739F@gmail.com> X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Howard Melman > Date: Sat, 21 May 2022 13:49:48 -0400 > Cc: 55527@debbugs.gnu.org > > The existing docstrings for these commands had "word(s)" in them > and I don't think that's what made them unclear. I also think it's a > common case to define an abbrev for a multi-word expansion. I disagree, and let's leave it at that. > Also, I see now that the inverse- versions of these command treat a > negative argument as reversing the direction to find the word to use > as the abbreviation but the (old and new) docstrings fails to mention > this. I'm not sure if that's intentional or not (IMO it's an odd use case). This is unrelated. The effect of negative argument was implied; I've now made it explicit. Our disagreement aside, are there any other issues left? From unknown Sun Jun 22 03:57:07 2025 X-Loop: help-debbugs@gnu.org Subject: bug#55527: 28.1; Clearer abbrev docstrings Resent-From: Howard Melman Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 21 May 2022 18:27:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 55527 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Eli Zaretskii Cc: 55527@debbugs.gnu.org Received: via spool by 55527-submit@debbugs.gnu.org id=B55527.16531576015805 (code B ref 55527); Sat, 21 May 2022 18:27:01 +0000 Received: (at 55527) by debbugs.gnu.org; 21 May 2022 18:26:41 +0000 Received: from localhost ([127.0.0.1]:42925 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nsToH-0001VZ-6K for submit@debbugs.gnu.org; Sat, 21 May 2022 14:26:41 -0400 Received: from mail-qt1-f175.google.com ([209.85.160.175]:35477) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nsToC-0001VK-KU for 55527@debbugs.gnu.org; Sat, 21 May 2022 14:26:39 -0400 Received: by mail-qt1-f175.google.com with SMTP id h9so5549907qtx.2 for <55527@debbugs.gnu.org>; Sat, 21 May 2022 11:26:36 -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=6uZtSyjhUrfXkyLrO8Q7IRN2dWMwFiJrkyXEIXVcPXw=; b=Fykplf3gq/Tnho1NTDPFEpxm3ehozMecPITUzqokH2r9TmQIIyLtq9Sq5+TV3px8Z0 4EPLYJXtPL15kGsoetr1ENSZ+aW+2Xcsy+Hpz2hBetPuv/8PBYxLanDNd/juiN4yRyjK Y2ZcWT1dIO61hS8ni2waQnheHL9whfxsQdSf/+kP48wLerxAL75dHkVQcEkqNRAgNZxF lHDpf5gG+whLciVy0EP4nP2gsMNsXiNfi6FJRvh4IMBmxigCyHB1xG0WGwoz7PRa/Cmu Zt+Vl2xmwfp5FQsKzCVV0uSN/4V4uAWZ3eL3OjhT4U2GdDtpG+jL0IuSDYESCeGCz0+5 72Vw== 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=6uZtSyjhUrfXkyLrO8Q7IRN2dWMwFiJrkyXEIXVcPXw=; b=opbP0JbKM0ihsRbbyYGsKJtbHKMenvV82q1B4pT/x+H8CQMbDCdP0XkIKhCatMxNKx M8dsLLDVpCIni6Jp3xcVaGMsQ+TmqlIR8A22aWCjPkprLQI7daSIUE9qES5/yVP/SfYc /YQw8Ba4yTYH6LFviFDpOU41gngzEsndxlX5KrlZFwh/b7cajB9UJprJE5KPBtOyHlZ6 bUyzW/G13XzSzFwrcJiQ6zSb8TBGJbE32DcRMkAafG1I1Wi32mbQ6kuRPBZyPOwYE57F WRrTE/q8Wx1OIiuCNOb8RtcmsXE2EAtfl/xXcz0bmK4hBGUNrkM+jCtEq1n0aTEizmYk ljgg== X-Gm-Message-State: AOAM530lIgU/T2ipgN85+kKcXMUyDCPKS973V9+6bCxQ62Y4SDtvsdmg pDxdC0vM1Di8o8Hs+oHEr20= X-Google-Smtp-Source: ABdhPJwmBGK+7PvEvCNum9YXx2QJ+Haj3v7iPMHnW6PMn5VDr29yU5cTbumuknSOY/DbQR8i24SeVQ== X-Received: by 2002:a05:622a:178a:b0:2f9:2257:69e3 with SMTP id s10-20020a05622a178a00b002f9225769e3mr4980248qtk.568.1653157591086; Sat, 21 May 2022 11:26:31 -0700 (PDT) Received: from smtpclient.apple (pool-108-26-204-101.bstnma.fios.verizon.net. [108.26.204.101]) by smtp.gmail.com with ESMTPSA id u65-20020a379244000000b0069fc13ce20asm1697057qkd.59.2022.05.21.11.26.30 (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Sat, 21 May 2022 11:26:30 -0700 (PDT) Content-Type: text/plain; charset=us-ascii Mime-Version: 1.0 (Mac OS X Mail 14.0 \(3654.120.0.1.13\)) From: Howard Melman In-Reply-To: <83bkvq92wm.fsf@gnu.org> Date: Sat, 21 May 2022 14:26:29 -0400 Content-Transfer-Encoding: quoted-printable Message-Id: References: <83bkvtcq38.fsf@gnu.org> <838rqxcnkk.fsf@gnu.org> <837d6gdaab.fsf@gnu.org> <83leuw9ovm.fsf@gnu.org> <27EF500E-25FC-4079-AA2F-66A8B3CA95B5@gmail.com> <838rqv9wnp.fsf@gnu.org> <6DB8A7EA-325F-4E1D-8382-431581A07B95@gmail.com> <83fsl37z9k.fsf@gnu.org> <96FE2CC0-8A4C-4099-A3D5-5FDD351C739F@gmail.com> <83bkvq92wm.fsf@gnu.org> X-Mailer: Apple Mail (2.3654.120.0.1.13) X-Spam-Score: -0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) > On May 21, 2022, at 2:06 PM, Eli Zaretskii wrote: >=20 >> From: Howard Melman >> Date: Sat, 21 May 2022 13:49:48 -0400 >> Cc: 55527@debbugs.gnu.org >>=20 >> The existing docstrings for these commands had "word(s)" in them >> and I don't think that's what made them unclear. I also think it's a >> common case to define an abbrev for a multi-word expansion. >=20 > I disagree, and let's leave it at that. >=20 >> Also, I see now that the inverse- versions of these command treat a=20= >> negative argument as reversing the direction to find the word to use >> as the abbreviation but the (old and new) docstrings fails to mention=20= >> this. I'm not sure if that's intentional or not (IMO it's an odd use = case). >=20 > This is unrelated. The effect of negative argument was implied; I've > now made it explicit. >=20 > Our disagreement aside, are there any other issues left? Nope. Thanks. Howard= From unknown Sun Jun 22 03:57:07 2025 MIME-Version: 1.0 X-Mailer: MIME-tools 5.505 (Entity 5.505) X-Loop: help-debbugs@gnu.org From: help-debbugs@gnu.org (GNU bug Tracking System) To: Howard Melman Subject: bug#55527: closed (Re: bug#55527: 28.1; Clearer abbrev docstrings) Message-ID: References: <83a6ba911r.fsf@gnu.org> X-Gnu-PR-Message: they-closed 55527 X-Gnu-PR-Package: emacs Reply-To: 55527@debbugs.gnu.org Date: Sat, 21 May 2022 18:47:02 +0000 Content-Type: multipart/mixed; boundary="----------=_1653158822-7795-1" This is a multi-part message in MIME format... ------------=_1653158822-7795-1 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Your bug report #55527: 28.1; Clearer abbrev docstrings which was filed against the emacs package, has been closed. The explanation is attached below, along with your original report. If you require more details, please reply to 55527@debbugs.gnu.org. --=20 55527: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=3D55527 GNU Bug Tracking System Contact help-debbugs@gnu.org with problems ------------=_1653158822-7795-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at 55527-done) by debbugs.gnu.org; 21 May 2022 18:46:50 +0000 Received: from localhost ([127.0.0.1]:42946 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nsU7m-00020z-DM for submit@debbugs.gnu.org; Sat, 21 May 2022 14:46:50 -0400 Received: from eggs.gnu.org ([209.51.188.92]:51700) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nsU7h-00020U-ST for 55527-done@debbugs.gnu.org; Sat, 21 May 2022 14:46:47 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:55622) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nsU7N-0000JS-QF; Sat, 21 May 2022 14:46:40 -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=Msx0aTdhML4rER92K0Oa8gifzTSGMeBp82vU5ijYPa8=; b=AfW3GLYwvWd/ 6xGuG9Lt1he1Lkc21/ZOThL/00/FU+ZnV45igijxxVdyU/zVpK/TF1DxLRHH3ysWJ1/fzo0kmShW2 HCWfby6zdcumJhx3x+3+bu13jF6jQvgq04/aD9TGOmF65pY8HPyILYCFh+EitgpqzlaCgfGMl42jX EqczwolQ+/h8yvdirTWUV5el40kGzT9I7qO3e0nffTFqYeWtv8sqq3lY7RF4v0B7lakf6vIHAbwgz sxiJtuqxVjLJw7vVHCD9cKGSBt1YKgYuDjNQzdiXP3qAHYN2Y0+FKdHhcczxSJ8nTbycJvQMkC8E0 uiA+MImPCkZA8NQbPhvQDQ==; Received: from [87.69.77.57] (port=2921 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 1nsU7N-0003IR-9r; Sat, 21 May 2022 14:46:25 -0400 Date: Sat, 21 May 2022 21:46:08 +0300 Message-Id: <83a6ba911r.fsf@gnu.org> From: Eli Zaretskii To: Howard Melman In-Reply-To: (message from Howard Melman on Sat, 21 May 2022 14:26:29 -0400) Subject: Re: bug#55527: 28.1; Clearer abbrev docstrings References: <83bkvtcq38.fsf@gnu.org> <838rqxcnkk.fsf@gnu.org> <837d6gdaab.fsf@gnu.org> <83leuw9ovm.fsf@gnu.org> <27EF500E-25FC-4079-AA2F-66A8B3CA95B5@gmail.com> <838rqv9wnp.fsf@gnu.org> <6DB8A7EA-325F-4E1D-8382-431581A07B95@gmail.com> <83fsl37z9k.fsf@gnu.org> <96FE2CC0-8A4C-4099-A3D5-5FDD351C739F@gmail.com> <83bkvq92wm.fsf@gnu.org> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 55527-done Cc: 55527-done@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Howard Melman > Date: Sat, 21 May 2022 14:26:29 -0400 > Cc: 55527@debbugs.gnu.org > > > > > Our disagreement aside, are there any other issues left? > > Nope. Thanks. Great, thanks. So I'm closing this bug. ------------=_1653158822-7795-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at submit) by debbugs.gnu.org; 19 May 2022 18:32:58 +0000 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 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 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 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 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) 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) From: Howard Melman Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable Mime-Version: 1.0 (Mac OS X Mail 14.0 \(3654.120.0.1.13\)) Subject: 28.1; Clearer abbrev docstrings Message-Id: Date: Thu, 19 May 2022 14:32:44 -0400 To: GNU Emacs 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-Spam-Score: -1.3 (-) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.3 (--) 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 ------------=_1653158822-7795-1--