From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Juri Linkov Newsgroups: gmane.emacs.bugs Subject: bug#50303: Add interlinks to docstrings of inverse abbrev Date: Tue, 31 Aug 2021 21:11:05 +0300 Organization: LINKOV.NET Message-ID: <87r1e9mq5q.fsf@mail.linkov.net> References: <87tuj5shs3.fsf@mail.linkov.net> <837dg1seb8.fsf@gnu.org> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="28034"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (x86_64-pc-linux-gnu) Cc: 50303@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Tue Aug 31 20:23:17 2021 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 1mL8Pl-00073J-Aw for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 31 Aug 2021 20:23:17 +0200 Original-Received: from localhost ([::1]:39532 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mL8Pj-0005Np-PJ for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 31 Aug 2021 14:23:15 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:37184) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mL8PX-0005Nf-FO for bug-gnu-emacs@gnu.org; Tue, 31 Aug 2021 14:23:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:52053) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mL8PX-0005Wl-00 for bug-gnu-emacs@gnu.org; Tue, 31 Aug 2021 14:23:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1mL8PW-0001ek-Gt for bug-gnu-emacs@gnu.org; Tue, 31 Aug 2021 14:23:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Juri Linkov Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 31 Aug 2021 18:23:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 50303 X-GNU-PR-Package: emacs Original-Received: via spool by 50303-submit@debbugs.gnu.org id=B50303.16304341446302 (code B ref 50303); Tue, 31 Aug 2021 18:23:02 +0000 Original-Received: (at 50303) by debbugs.gnu.org; 31 Aug 2021 18:22:24 +0000 Original-Received: from localhost ([127.0.0.1]:35366 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mL8Ou-0001da-Fw for submit@debbugs.gnu.org; Tue, 31 Aug 2021 14:22:24 -0400 Original-Received: from relay6-d.mail.gandi.net ([217.70.183.198]:51541) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mL8Or-0001dJ-TS for 50303@debbugs.gnu.org; Tue, 31 Aug 2021 14:22:22 -0400 Original-Received: (Authenticated sender: juri@linkov.net) by relay6-d.mail.gandi.net (Postfix) with ESMTPSA id 5BC88C0007; Tue, 31 Aug 2021 18:22:14 +0000 (UTC) In-Reply-To: <837dg1seb8.fsf@gnu.org> (Eli Zaretskii's message of "Tue, 31 Aug 2021 20:40:27 +0300") 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:213119 Archived-At: --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit >> @@ -287,6 +287,7 @@ add-mode-abbrev >> +You can also use the opposite command `inverse-add-mode-abbrev'. > > Thanks, but I think "you can also use" is not the best text here. It > could be interpreted to mean that the other command does something > similar, which is not true, and contradicts the "opposite" part. > This makes the text confusing. > > How about saying explicitly what that command does. For example: > > To define expansion for the word at point, use `inverse-add-mode-abbrev'. > > And similarly for the other doc strings. The intention was to indicate that these are opposite commands. A good explanation is in (info "(emacs) Defining Abbrevs"): ‘C-x a i g’ (‘inverse-add-global-abbrev’) and ‘C-x a i l’ (‘inverse-add-mode-abbrev’) perform the opposite task: if the abbrev text is already in the buffer, you use these commands to define an abbrev by specifying the expansion in the minibuffer. These commands will expand the abbrev text used for the definition. Also to reduce confusion, to explicitly mention what another command does: 1. the abbrev is in the buffer, read the expansion from the minibuffer 2. the expansion is in the buffer, read the abbrev from the minibuffer So maybe this patch is better: --=-=-= Content-Type: text/x-diff Content-Disposition: inline; filename=abbrev-docstrings-2.patch diff --git a/lisp/abbrev.el b/lisp/abbrev.el index 54783db2c3..74c9a49b3b 100644 --- a/lisp/abbrev.el +++ b/lisp/abbrev.el @@ -288,6 +288,9 @@ add-mode-abbrev A negative argument means to undefine the specified abbrev. Reads the abbreviation in the minibuffer. +Instead of this, to read the expansion in the minibuffer +for the abbreviation at point, use `inverse-add-mode-abbrev'. + Don't use this function in a Lisp program; use `define-abbrev' instead." (interactive "p") (add-abbrev @@ -304,6 +307,9 @@ add-global-abbrev A negative argument means to undefine the specified abbrev. This command uses the minibuffer to read the abbreviation. +Instead of this, to read the expansion in the minibuffer +for the abbreviation at point, use `inverse-add-global-abbrev'. + Don't use this function in a Lisp program; use `define-abbrev' instead." (interactive "p") (add-abbrev global-abbrev-table "Global" arg)) @@ -330,7 +336,10 @@ inverse-add-mode-abbrev "Define last word before point as a mode-specific abbrev. With prefix argument N, defines the Nth word before point. This command uses the minibuffer to read the expansion. -Expands the abbreviation after defining it." +Expands the abbreviation after defining it. + +Instead of this, to read the abbreviation in the minibuffer +for the expansion at point, use `add-mode-abbrev'." (interactive "p") (inverse-add-abbrev (if only-global-abbrevs @@ -343,7 +352,10 @@ inverse-add-global-abbrev "Define last word before point as a global (mode-independent) abbrev. With prefix argument N, defines the Nth word before point. This command uses the minibuffer to read the expansion. -Expands the abbreviation after defining it." +Expands the abbreviation after defining it. + +Instead of this, to read the abbreviation in the minibuffer +for the expansion at point, use `add-global-abbrev'." (interactive "p") (inverse-add-abbrev global-abbrev-table "Global" n)) --=-=-=--