GNU bug report logs - #30610
clarify linum-mode usage from Lisp

Previous Next

Package: emacs;

Reported by: John Shahid <jvshahid <at> gmail.com>

Date: Sun, 25 Feb 2018 23:26:02 UTC

Severity: minor

Fixed in version 27.1

Done: Stefan Kangas <stefan <at> marxist.se>

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 30610 in the body.
You can then email your comments to 30610 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to bug-gnu-emacs <at> gnu.org:
bug#30610; Package emacs. (Sun, 25 Feb 2018 23:26:02 GMT) Full text and rfc822 format available.

Acknowledgement sent to John Shahid <jvshahid <at> gmail.com>:
New bug report received and forwarded. Copy sent to bug-gnu-emacs <at> gnu.org. (Sun, 25 Feb 2018 23:26:02 GMT) Full text and rfc822 format available.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: John Shahid <jvshahid <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: clarify linux-mode usage from Lisp
Date: Sun, 25 Feb 2018 14:55:53 -0500
[0001-clarifies-linum-mode-usage-from-Lisp.patch (text/x-diff, inline)]
From 04d261f836e5b000e8f6ed9e343417feaa8bc273 Mon Sep 17 00:00:00 2001
From: John Shahid <jvshahid <at> gmail.com>
Date: Sun, 25 Feb 2018 14:33:00 -0500
Subject: [PATCH] clarifies linum-mode usage from Lisp

---
 lisp/linum.el | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/lisp/linum.el b/lisp/linum.el
index 9df0c5d023..fa66d62bfe 100644
--- a/lisp/linum.el
+++ b/lisp/linum.el
@@ -76,8 +76,12 @@ linum-delay
 (define-minor-mode linum-mode
   "Toggle display of line numbers in the left margin (Linum mode).
 With a prefix argument ARG, enable Linum mode if ARG is positive,
-and disable it otherwise.  If called from Lisp, enable the mode
-if ARG is omitted or nil.
+and disable it otherwise.
+
+When called from Lisp, toggles the mode if the argument is
+`toggle', disables the mode if the argument is a non-positive
+integer, and enables the mode otherwise (including if the
+argument is omitted or nil or a positive integer).
 
 Linum mode is a buffer-local minor mode."
   :lighter ""                           ; for desktop.el
-- 
2.16.2

[Message part 2 (text/plain, inline)]
The attached patch fixes a bug in the docstring of linum-mode regarding
calling it from Lisp. It incorrectly state that calling the function
with no args or nil will enable the mode; this gives the impression that
any other value disables the mode, which isn't the case. The patches
copies the relevant section from define-minor-mode

cheers,

-js

Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#30610; Package emacs. (Mon, 26 Feb 2018 01:52:01 GMT) Full text and rfc822 format available.

Message #8 received at submit <at> debbugs.gnu.org (full text, mbox):

From: John Shahid <jvshahid <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: Re: clarify linux-mode usage from Lisp
Date: Sun, 25 Feb 2018 15:12:54 -0500
Worth noting that this is my first patch to Emacs. Let me know if
there's anything wrong with the way I submitted the patch.

cheers,

-js

John Shahid <jvshahid <at> gmail.com> writes:

> From 04d261f836e5b000e8f6ed9e343417feaa8bc273 Mon Sep 17 00:00:00 2001
> From: John Shahid <jvshahid <at> gmail.com>
> Date: Sun, 25 Feb 2018 14:33:00 -0500
> Subject: [PATCH] clarifies linum-mode usage from Lisp
>
> ---
>  lisp/linum.el | 8 ++++++--
>  1 file changed, 6 insertions(+), 2 deletions(-)
>
> diff --git a/lisp/linum.el b/lisp/linum.el
> index 9df0c5d023..fa66d62bfe 100644
> --- a/lisp/linum.el
> +++ b/lisp/linum.el
> @@ -76,8 +76,12 @@ linum-delay
>  (define-minor-mode linum-mode
>    "Toggle display of line numbers in the left margin (Linum mode).
>  With a prefix argument ARG, enable Linum mode if ARG is positive,
> -and disable it otherwise.  If called from Lisp, enable the mode
> -if ARG is omitted or nil.
> +and disable it otherwise.
> +
> +When called from Lisp, toggles the mode if the argument is
> +`toggle', disables the mode if the argument is a non-positive
> +integer, and enables the mode otherwise (including if the
> +argument is omitted or nil or a positive integer).
>  
>  Linum mode is a buffer-local minor mode."
>    :lighter ""                           ; for desktop.el





Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#30610; Package emacs. (Fri, 02 Mar 2018 03:27:02 GMT) Full text and rfc822 format available.

Message #11 received at 30610 <at> debbugs.gnu.org (full text, mbox):

From: Noam Postavsky <npostavs <at> gmail.com>
To: John Shahid <jvshahid <at> gmail.com>
Cc: 30610 <at> debbugs.gnu.org
Subject: Re: bug#30610: clarify linux-mode usage from Lisp
Date: Thu, 01 Mar 2018 22:26:02 -0500
John Shahid <jvshahid <at> gmail.com> writes:

> Worth noting that this is my first patch to Emacs. Let me know if
> there's anything wrong with the way I submitted the patch.

The patch looks fine, but the commit message should have a ChangeLog
style entry as described in CONTRIBUTE under "Commit messages".  And if
you haven't assigned copyright for Emacs, it should also have a
'Copyright-paperwork-exempt: yes' line.  Note that we only accept up to
15 lines worth of unassigned patches.  If you want to start the
assignment process, fill out the form at [1] and send it to
fsf-records <at> gnu.org (they will reply with further instructions).

[1]: https://git.savannah.gnu.org/cgit/gnulib.git/tree/doc/Copyright/request-assign.program




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#30610; Package emacs. (Sat, 03 Mar 2018 23:18:01 GMT) Full text and rfc822 format available.

Message #14 received at 30610 <at> debbugs.gnu.org (full text, mbox):

From: John Shahid <jvshahid <at> gmail.com>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: 30610 <at> debbugs.gnu.org
Subject: Re: bug#30610: clarify linux-mode usage from Lisp
Date: Sat, 03 Mar 2018 18:17:19 -0500
[Message part 1 (text/plain, inline)]
Noam Postavsky <npostavs <at> gmail.com> writes:

> John Shahid <jvshahid <at> gmail.com> writes:
>
>> Worth noting that this is my first patch to Emacs. Let me know if
>> there's anything wrong with the way I submitted the patch.
>
> The patch looks fine, but the commit message should have a ChangeLog
> style entry as described in CONTRIBUTE under "Commit messages".

fixed and attached a new patch

> And if you haven't assigned copyright for Emacs, it should also have a
> 'Copyright-paperwork-exempt: yes' line.  Note that we only accept up
> to 15 lines worth of unassigned patches.  If you want to start the
> assignment process, fill out the form at [1] and send it to
> fsf-records <at> gnu.org (they will reply with further instructions).

i filled out and sent the paper work. i also exempt this commit from the
paperwork since it is a very minor change.

thanks,

-js

[0001-lisp-linum.el-clarify-linum-mode-handling-of-ARG.patch (text/x-diff, inline)]
From 113b30d8739dc8d1673a53d06b201e6c9ea1a54a Mon Sep 17 00:00:00 2001
From: John Shahid <jvshahid <at> gmail.com>
Date: Sun, 25 Feb 2018 14:33:00 -0500
Subject: [PATCH] lisp/linum.el: clarify linum-mode handling of `ARG'

Copyright-paperwork-exempt: yes
---
 lisp/linum.el | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/lisp/linum.el b/lisp/linum.el
index 9df0c5d023..fa66d62bfe 100644
--- a/lisp/linum.el
+++ b/lisp/linum.el
@@ -76,8 +76,12 @@ linum-delay
 (define-minor-mode linum-mode
   "Toggle display of line numbers in the left margin (Linum mode).
 With a prefix argument ARG, enable Linum mode if ARG is positive,
-and disable it otherwise.  If called from Lisp, enable the mode
-if ARG is omitted or nil.
+and disable it otherwise.
+
+When called from Lisp, toggles the mode if the argument is
+`toggle', disables the mode if the argument is a non-positive
+integer, and enables the mode otherwise (including if the
+argument is omitted or nil or a positive integer).
 
 Linum mode is a buffer-local minor mode."
   :lighter ""                           ; for desktop.el
-- 
2.16.2


Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#30610; Package emacs. (Sat, 03 Mar 2018 23:25:02 GMT) Full text and rfc822 format available.

Message #17 received at 30610 <at> debbugs.gnu.org (full text, mbox):

From: John Shahid <jvshahid <at> gmail.com>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: 30610 <at> debbugs.gnu.org
Subject: Re: bug#30610: clarify linux-mode usage from Lisp
Date: Sat, 03 Mar 2018 18:24:04 -0500
[Message part 1 (text/plain, inline)]
forgot to add asterisk before the file name. attached the new patch with
the asterisk

John Shahid <jvshahid <at> gmail.com> writes:

> Noam Postavsky <npostavs <at> gmail.com> writes:
>
>> John Shahid <jvshahid <at> gmail.com> writes:
>>
>>> Worth noting that this is my first patch to Emacs. Let me know if
>>> there's anything wrong with the way I submitted the patch.
>>
>> The patch looks fine, but the commit message should have a ChangeLog
>> style entry as described in CONTRIBUTE under "Commit messages".
>
> fixed and attached a new patch
>
>> And if you haven't assigned copyright for Emacs, it should also have a
>> 'Copyright-paperwork-exempt: yes' line.  Note that we only accept up
>> to 15 lines worth of unassigned patches.  If you want to start the
>> assignment process, fill out the form at [1] and send it to
>> fsf-records <at> gnu.org (they will reply with further instructions).
>
> i filled out and sent the paper work. i also exempt this commit from the
> paperwork since it is a very minor change.
>
> thanks,
>
> -js
>
> From 113b30d8739dc8d1673a53d06b201e6c9ea1a54a Mon Sep 17 00:00:00 2001
> From: John Shahid <jvshahid <at> gmail.com>
> Date: Sun, 25 Feb 2018 14:33:00 -0500
> Subject: [PATCH] lisp/linum.el: clarify linum-mode handling of `ARG'
>
> Copyright-paperwork-exempt: yes
> ---
>  lisp/linum.el | 8 ++++++--
>  1 file changed, 6 insertions(+), 2 deletions(-)
>
> diff --git a/lisp/linum.el b/lisp/linum.el
> index 9df0c5d023..fa66d62bfe 100644
> --- a/lisp/linum.el
> +++ b/lisp/linum.el
> @@ -76,8 +76,12 @@ linum-delay
>  (define-minor-mode linum-mode
>    "Toggle display of line numbers in the left margin (Linum mode).
>  With a prefix argument ARG, enable Linum mode if ARG is positive,
> -and disable it otherwise.  If called from Lisp, enable the mode
> -if ARG is omitted or nil.
> +and disable it otherwise.
> +
> +When called from Lisp, toggles the mode if the argument is
> +`toggle', disables the mode if the argument is a non-positive
> +integer, and enables the mode otherwise (including if the
> +argument is omitted or nil or a positive integer).
>  
>  Linum mode is a buffer-local minor mode."
>    :lighter ""                           ; for desktop.el

[0001-lisp-linum.el-clarify-linum-mode-handling-of-ARG.patch (text/x-diff, inline)]
From 7024af1df6fccedbdba1ea24337f417cbb03a6a2 Mon Sep 17 00:00:00 2001
From: John Shahid <jvshahid <at> gmail.com>
Date: Sun, 25 Feb 2018 14:33:00 -0500
Subject: [PATCH] * lisp/linum.el: clarify linum-mode handling of `ARG'

Copyright-paperwork-exempt: yes
---
 lisp/linum.el | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/lisp/linum.el b/lisp/linum.el
index 9df0c5d023..fa66d62bfe 100644
--- a/lisp/linum.el
+++ b/lisp/linum.el
@@ -76,8 +76,12 @@ linum-delay
 (define-minor-mode linum-mode
   "Toggle display of line numbers in the left margin (Linum mode).
 With a prefix argument ARG, enable Linum mode if ARG is positive,
-and disable it otherwise.  If called from Lisp, enable the mode
-if ARG is omitted or nil.
+and disable it otherwise.
+
+When called from Lisp, toggles the mode if the argument is
+`toggle', disables the mode if the argument is a non-positive
+integer, and enables the mode otherwise (including if the
+argument is omitted or nil or a positive integer).
 
 Linum mode is a buffer-local minor mode."
   :lighter ""                           ; for desktop.el
-- 
2.16.2


Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#30610; Package emacs. (Sun, 04 Mar 2018 01:51:02 GMT) Full text and rfc822 format available.

Message #20 received at 30610 <at> debbugs.gnu.org (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: John Shahid <jvshahid <at> gmail.com>
Cc: Noam Postavsky <npostavs <at> gmail.com>, 30610 <at> debbugs.gnu.org
Subject: Re: bug#30610: clarify linux-mode usage from Lisp
Date: Sat, 03 Mar 2018 20:49:51 -0500
There are loads of these "Toggle..." doc-strings, all using the same
format. It doesn't make sense to change just the linum one.

(https://debbugs.gnu.org/10754 would reduce the need to change multiple
places in future.)




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#30610; Package emacs. (Sun, 04 Mar 2018 02:15:02 GMT) Full text and rfc822 format available.

Message #23 received at 30610 <at> debbugs.gnu.org (full text, mbox):

From: John Shahid <jvshahid <at> gmail.com>
To: Glenn Morris <rgm <at> gnu.org>
Cc: Noam Postavsky <npostavs <at> gmail.com>, 30610 <at> debbugs.gnu.org
Subject: Re: bug#30610: clarify linux-mode usage from Lisp
Date: Sat, 03 Mar 2018 21:14:35 -0500
Agreed. I like your proposed solution more. do you have patch or is that
something I can work on ?

Glenn Morris <rgm <at> gnu.org> writes:

> There are loads of these "Toggle..." doc-strings, all using the same
> format. It doesn't make sense to change just the linum one.
>
> (https://debbugs.gnu.org/10754 would reduce the need to change multiple
> places in future.)




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#30610; Package emacs. (Sun, 04 Mar 2018 02:24:02 GMT) Full text and rfc822 format available.

Message #26 received at 30610 <at> debbugs.gnu.org (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: John Shahid <jvshahid <at> gmail.com>, 30610 <at> debbugs.gnu.org
Subject: Re: bug#30610: clarify linux-mode usage from Lisp
Date: Sat, 03 Mar 2018 21:22:58 -0500
Noam Postavsky wrote:

> https://git.savannah.gnu.org/cgit/gnulib.git/tree/doc/Copyright/request-assign.program

BTW, I think request-assign.future is the one to use in (al)most (all)
situations.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#30610; Package emacs. (Sun, 04 Mar 2018 17:41:02 GMT) Full text and rfc822 format available.

Message #29 received at 30610 <at> debbugs.gnu.org (full text, mbox):

From: John Shahid <jvshahid <at> gmail.com>
To: Glenn Morris <rgm <at> gnu.org>
Cc: Noam Postavsky <npostavs <at> gmail.com>, 30610 <at> debbugs.gnu.org
Subject: Re: bug#30610: clarify linux-mode usage from Lisp
Date: Sun, 04 Mar 2018 12:40:49 -0500
Glenn Morris <rgm <at> gnu.org> writes:

> Noam Postavsky wrote:
>
>> https://git.savannah.gnu.org/cgit/gnulib.git/tree/doc/Copyright/request-assign.program
>
> BTW, I think request-assign.future is the one to use in (al)most (all)
> situations.

I submitted both.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#30610; Package emacs. (Tue, 20 Aug 2019 12:23:01 GMT) Full text and rfc822 format available.

Message #32 received at 30610 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: John Shahid <jvshahid <at> gmail.com>
Cc: 30610 <at> debbugs.gnu.org
Subject: Re: bug#30610: clarify linux-mode usage from Lisp
Date: Tue, 20 Aug 2019 14:22:00 +0200
close 30610 27.1
quit

John Shahid <jvshahid <at> gmail.com> writes:

>>From 04d261f836e5b000e8f6ed9e343417feaa8bc273 Mon Sep 17 00:00:00 2001
> From: John Shahid <jvshahid <at> gmail.com>
> Date: Sun, 25 Feb 2018 14:33:00 -0500
> Subject: [PATCH] clarifies linum-mode usage from Lisp
>
> ---
>  lisp/linum.el | 8 ++++++--
>  1 file changed, 6 insertions(+), 2 deletions(-)
>
> diff --git a/lisp/linum.el b/lisp/linum.el
> index 9df0c5d023..fa66d62bfe 100644
> --- a/lisp/linum.el
> +++ b/lisp/linum.el
> @@ -76,8 +76,12 @@ linum-delay
>  (define-minor-mode linum-mode
>    "Toggle display of line numbers in the left margin (Linum mode).
>  With a prefix argument ARG, enable Linum mode if ARG is positive,
> -and disable it otherwise.  If called from Lisp, enable the mode
> -if ARG is omitted or nil.
> +and disable it otherwise.
> +
> +When called from Lisp, toggles the mode if the argument is
> +`toggle', disables the mode if the argument is a non-positive
> +integer, and enables the mode otherwise (including if the
> +argument is omitted or nil or a positive integer).
>
>  Linum mode is a buffer-local minor mode."
>    :lighter ""                           ; for desktop.el
> --
> 2.16.2
>
> The attached patch fixes a bug in the docstring of linum-mode regarding
> calling it from Lisp. It incorrectly state that calling the function
> with no args or nil will enable the mode; this gives the impression that
> any other value disables the mode, which isn't the case. The patches
> copies the relevant section from define-minor-mode

This issue seems to have been fixed on master in:

commit ee3e432300054ca488896e39fca57b10d733330a
Author: John Shahid <jvshahid <at> gmail.com>
Date:   Sun Jul 1 23:34:53 2018 -0400

    Optionally add argument description in minor mode DOC (bug#10754)

I'm therefore closing this bug report.

Thanks,
Stefan Kangas




bug marked as fixed in version 27.1, send any further explanations to 30610 <at> debbugs.gnu.org and John Shahid <jvshahid <at> gmail.com> Request was from Stefan Kangas <stefan <at> marxist.se> to control <at> debbugs.gnu.org. (Tue, 20 Aug 2019 12:23: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. (Wed, 18 Sep 2019 11:24:06 GMT) Full text and rfc822 format available.

This bug report was last modified 4 years and 194 days ago.

Previous Next


GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.