From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Howard Melman Newsgroups: gmane.emacs.bugs Subject: bug#55527: 28.1; Clearer abbrev docstrings Date: Sat, 21 May 2022 13:49:48 -0400 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> Mime-Version: 1.0 (Mac OS X Mail 14.0 \(3654.120.0.1.13\)) Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="7083"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 55527@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sat May 21 19:51:13 2022 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1nsTFw-0001dY-QD for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 21 May 2022 19:51:12 +0200 Original-Received: from localhost ([::1]:56356 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nsTFv-0005di-AF for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 21 May 2022 13:51:11 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:36764) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nsTFm-0005co-Sf for bug-gnu-emacs@gnu.org; Sat, 21 May 2022 13:51:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:49004) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1nsTFm-0000mS-K9 for bug-gnu-emacs@gnu.org; Sat, 21 May 2022 13:51:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1nsTFm-0000d7-Gu for bug-gnu-emacs@gnu.org; Sat, 21 May 2022 13:51:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Howard Melman Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: 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 Original-Received: via spool by 55527-submit@debbugs.gnu.org id=B55527.16531554082353 (code B ref 55527); Sat, 21 May 2022 17:51:02 +0000 Original-Received: (at 55527) by debbugs.gnu.org; 21 May 2022 17:50:08 +0000 Original-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 Original-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 Original-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) Original-Received: from smtpclient.apple (pool-108-26-204-101.bstnma.fios.verizon.net. [108.26.204.101]) by smtp.gmail.com with ESMTPSA id 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) In-Reply-To: <83fsl37z9k.fsf@gnu.org> X-Mailer: Apple Mail (2.3654.120.0.1.13) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:232842 Archived-At: 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