GNU bug report logs -
#50303
Add interlinks to docstrings of inverse abbrev
Previous Next
Reported by: Juri Linkov <juri <at> linkov.net>
Date: Tue, 31 Aug 2021 17:00:02 UTC
Severity: normal
Tags: fixed, patch
Fixed in version 28.0.50
Done: Juri Linkov <juri <at> linkov.net>
Bug is archived. No further changes may be made.
To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 50303 in the body.
You can then email your comments to 50303 AT debbugs.gnu.org in the normal way.
Toggle the display of automated, internal messages from the tracker.
Report forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#50303
; Package
emacs
.
(Tue, 31 Aug 2021 17:00:02 GMT)
Full text and
rfc822 format available.
Acknowledgement sent
to
Juri Linkov <juri <at> linkov.net>
:
New bug report received and forwarded. Copy sent to
bug-gnu-emacs <at> gnu.org
.
(Tue, 31 Aug 2021 17:00:02 GMT)
Full text and
rfc822 format available.
Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):
[abbrev-docstrings.patch (text/x-diff, inline)]
diff --git a/lisp/abbrev.el b/lisp/abbrev.el
index 54783db2c3..0d754cc9cf 100644
--- a/lisp/abbrev.el
+++ b/lisp/abbrev.el
@@ -287,6 +287,7 @@ add-mode-abbrev
or zero means the region is the expansion.
A negative argument means to undefine the specified abbrev.
Reads the abbreviation in the minibuffer.
+You can also use the opposite command `inverse-add-mode-abbrev'.
Don't use this function in a Lisp program; use `define-abbrev' instead."
(interactive "p")
@@ -303,6 +304,7 @@ add-global-abbrev
expansion; or zero means the region is the expansion.
A negative argument means to undefine the specified abbrev.
This command uses the minibuffer to read the abbreviation.
+You can also use the opposite command `inverse-add-global-abbrev'.
Don't use this function in a Lisp program; use `define-abbrev' instead."
(interactive "p")
@@ -330,7 +332,8 @@ 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.
+You can also use the opposite command `add-mode-abbrev'."
(interactive "p")
(inverse-add-abbrev
(if only-global-abbrevs
@@ -343,7 +346,8 @@ 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.
+You can also use the opposite command `add-global-abbrev'."
(interactive "p")
(inverse-add-abbrev global-abbrev-table "Global" n))
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#50303
; Package
emacs
.
(Tue, 31 Aug 2021 17:41:02 GMT)
Full text and
rfc822 format available.
Message #8 received at 50303 <at> debbugs.gnu.org (full text, mbox):
> From: Juri Linkov <juri <at> linkov.net>
> Date: Tue, 31 Aug 2021 19:45:32 +0300
>
> diff --git a/lisp/abbrev.el b/lisp/abbrev.el
> index 54783db2c3..0d754cc9cf 100644
> --- a/lisp/abbrev.el
> +++ b/lisp/abbrev.el
> @@ -287,6 +287,7 @@ add-mode-abbrev
> or zero means the region is the expansion.
> A negative argument means to undefine the specified abbrev.
> Reads the abbreviation in the minibuffer.
> +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.
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#50303
; Package
emacs
.
(Tue, 31 Aug 2021 18:23:02 GMT)
Full text and
rfc822 format available.
Message #11 received at 50303 <at> debbugs.gnu.org (full text, mbox):
[Message part 1 (text/plain, inline)]
>> @@ -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:
[abbrev-docstrings-2.patch (text/x-diff, inline)]
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))
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#50303
; Package
emacs
.
(Tue, 31 Aug 2021 19:04:02 GMT)
Full text and
rfc822 format available.
Message #14 received at 50303 <at> debbugs.gnu.org (full text, mbox):
> From: Juri Linkov <juri <at> linkov.net>
> Cc: 50303 <at> debbugs.gnu.org
> Date: Tue, 31 Aug 2021 21:11:05 +0300
>
> >> +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.
I understand. But "opposite" is not well-defined in this case (it
could be a command that UN-defines an abbrev, for instance), and
therefore requires a long explanation:
> 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:
If you like what the manual says, why not say in the doc string what
the manual says, or some simple variant of that? I doubt that you'll
be able to come up with a significantly shorter description that is
still clear enough.
Thanks.
Added tag(s) patch.
Request was from
Lars Ingebrigtsen <larsi <at> gnus.org>
to
control <at> debbugs.gnu.org
.
(Wed, 01 Sep 2021 08:17:01 GMT)
Full text and
rfc822 format available.
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#50303
; Package
emacs
.
(Wed, 01 Sep 2021 15:46:02 GMT)
Full text and
rfc822 format available.
Message #19 received at 50303 <at> debbugs.gnu.org (full text, mbox):
[Message part 1 (text/plain, inline)]
>> 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.
>
> If you like what the manual says, why not say in the doc string what
> the manual says, or some simple variant of that? I doubt that you'll
> be able to come up with a significantly shorter description that is
> still clear enough.
So here it uses the text copied from the manual:
[abbrev-docstrings-3.patch (text/x-diff, inline)]
diff --git a/lisp/abbrev.el b/lisp/abbrev.el
index 54783db2c3..5b3804a006 100644
--- a/lisp/abbrev.el
+++ b/lisp/abbrev.el
@@ -288,6 +288,10 @@ add-mode-abbrev
A negative argument means to undefine the specified abbrev.
Reads the abbreviation in the minibuffer.
+`inverse-add-mode-abbrev' 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.
+
Don't use this function in a Lisp program; use `define-abbrev' instead."
(interactive "p")
(add-abbrev
@@ -304,6 +308,10 @@ add-global-abbrev
A negative argument means to undefine the specified abbrev.
This command uses the minibuffer to read the abbreviation.
+`inverse-add-global-abbrev' 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.
+
Don't use this function in a Lisp program; use `define-abbrev' instead."
(interactive "p")
(add-abbrev global-abbrev-table "Global" arg))
@@ -330,7 +338,11 @@ 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.
+
+`add-mode-abbrev' 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."
(interactive "p")
(inverse-add-abbrev
(if only-global-abbrevs
@@ -343,7 +355,11 @@ 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.
+
+`add-global-abbrev' 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."
(interactive "p")
(inverse-add-abbrev global-abbrev-table "Global" n))
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#50303
; Package
emacs
.
(Wed, 01 Sep 2021 16:09:02 GMT)
Full text and
rfc822 format available.
Message #22 received at 50303 <at> debbugs.gnu.org (full text, mbox):
> From: Juri Linkov <juri <at> linkov.net>
> Cc: 50303 <at> debbugs.gnu.org
> Date: Wed, 01 Sep 2021 18:37:13 +0300
>
> > If you like what the manual says, why not say in the doc string what
> > the manual says, or some simple variant of that? I doubt that you'll
> > be able to come up with a significantly shorter description that is
> > still clear enough.
>
> So here it uses the text copied from the manual:
Thanks, I think this is very good, but I'd like to suggest a minor
stylistic improvement:
> +`inverse-add-mode-abbrev' performs the opposite task: if the abbrev
I would begin this by saying
See also `inverse-add-mode-abbrev', which performs the opposite
task: ...
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#50303
; Package
emacs
.
(Thu, 02 Sep 2021 17:36:02 GMT)
Full text and
rfc822 format available.
Message #25 received at 50303 <at> debbugs.gnu.org (full text, mbox):
tags 50303 fixed
close 50303 28.0.50
quit
>> > If you like what the manual says, why not say in the doc string what
>> > the manual says, or some simple variant of that? I doubt that you'll
>> > be able to come up with a significantly shorter description that is
>> > still clear enough.
>>
>> So here it uses the text copied from the manual:
>
> Thanks, I think this is very good, but I'd like to suggest a minor
> stylistic improvement:
>
>> +`inverse-add-mode-abbrev' performs the opposite task: if the abbrev
>
> I would begin this by saying
>
> See also `inverse-add-mode-abbrev', which performs the opposite
> task: ...
Now pushed with this text.
Added tag(s) fixed.
Request was from
Juri Linkov <juri <at> linkov.net>
to
control <at> debbugs.gnu.org
.
(Thu, 02 Sep 2021 17:36:02 GMT)
Full text and
rfc822 format available.
bug marked as fixed in version 28.0.50, send any further explanations to
50303 <at> debbugs.gnu.org and Juri Linkov <juri <at> linkov.net>
Request was from
Juri Linkov <juri <at> linkov.net>
to
control <at> debbugs.gnu.org
.
(Thu, 02 Sep 2021 17:36:02 GMT)
Full text and
rfc822 format available.
bug archived.
Request was from
Debbugs Internal Request <help-debbugs <at> gnu.org>
to
internal_control <at> debbugs.gnu.org
.
(Fri, 01 Oct 2021 11:24:03 GMT)
Full text and
rfc822 format available.
This bug report was last modified 2 years and 208 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.