From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#55527: 28.1; Clearer abbrev docstrings Date: Sat, 21 May 2022 17:09:59 +0300 Message-ID: <83fsl37z9k.fsf@gnu.org> 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> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="7916"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 55527@debbugs.gnu.org To: Howard Melman Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sat May 21 16:11:14 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 1nsPp3-0001sv-Ve for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 21 May 2022 16:11:14 +0200 Original-Received: from localhost ([::1]:58668 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nsPp2-0002yk-Fi for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 21 May 2022 10:11:12 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:36432) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nsPos-0002yX-UD for bug-gnu-emacs@gnu.org; Sat, 21 May 2022 10:11:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:48867) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1nsPos-0004bk-Lr for bug-gnu-emacs@gnu.org; Sat, 21 May 2022 10:11:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1nsPos-0001EB-Fo for bug-gnu-emacs@gnu.org; Sat, 21 May 2022 10:11:02 -0400 X-Loop: help-debbugs@gnu.org 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 Original-Received: via spool by 55527-submit@debbugs.gnu.org id=B55527.16531422314679 (code B ref 55527); Sat, 21 May 2022 14:11:02 +0000 Original-Received: (at 55527) by debbugs.gnu.org; 21 May 2022 14:10:31 +0000 Original-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 Original-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 Original-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==; Original-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 In-Reply-To: <6DB8A7EA-325F-4E1D-8382-431581A07B95@gmail.com> (message from Howard Melman on Sat, 21 May 2022 09:41:41 -0400) 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:232836 Archived-At: > 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.