bug#30610: clarify linux-mode usage from Lisp

bug#30610: clarify linux-mode usage from Lisp

[John Shahid]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: 0001-clarifies-linum-mode-usage-from-Lisp.patch --]
[-- Type: text/x-diff, Size: 1071 bytes --]

From 04d261f836e5b000e8f6ed9e343417feaa8bc273 Mon Sep 17 00:00:00 2001
From: John Shahid <jvshahid@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


[-- Attachment #2: Type: text/plain, Size: 348 bytes --]

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

bug#30610: clarify linux-mode usage from Lisp

[John Shahid]

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@gmail.com> writes:

> From 04d261f836e5b000e8f6ed9e343417feaa8bc273 Mon Sep 17 00:00:00 2001
> From: John Shahid <jvshahid@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

bug#30610: clarify linux-mode usage from Lisp

[Noam Postavsky]

John Shahid <jvshahid@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@gnu.org (they will reply with further instructions).

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

bug#30610: clarify linux-mode usage from Lisp

[John Shahid]

[-- Attachment #1: Type: text/plain, Size: 868 bytes --]


Noam Postavsky <npostavs@gmail.com> writes:

> John Shahid <jvshahid@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@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


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-lisp-linum.el-clarify-linum-mode-handling-of-ARG.patch --]
[-- Type: text/x-diff, Size: 1118 bytes --]

From 113b30d8739dc8d1673a53d06b201e6c9ea1a54a Mon Sep 17 00:00:00 2001
From: John Shahid <jvshahid@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

bug#30610: clarify linux-mode usage from Lisp

[John Shahid]

[-- Attachment #1: Type: text/plain, Size: 2191 bytes --]


forgot to add asterisk before the file name. attached the new patch with
the asterisk

John Shahid <jvshahid@gmail.com> writes:

> Noam Postavsky <npostavs@gmail.com> writes:
>
>> John Shahid <jvshahid@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@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@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


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-lisp-linum.el-clarify-linum-mode-handling-of-ARG.patch --]
[-- Type: text/x-diff, Size: 1120 bytes --]

From 7024af1df6fccedbdba1ea24337f417cbb03a6a2 Mon Sep 17 00:00:00 2001
From: John Shahid <jvshahid@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

bug#30610: clarify linux-mode usage from Lisp

[Glenn Morris]

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.)

bug#30610: clarify linux-mode usage from Lisp

[John Shahid]

Agreed. I like your proposed solution more. do you have patch or is that
something I can work on ?

Glenn Morris <rgm@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.)

bug#30610: clarify linux-mode usage from Lisp

[Glenn Morris]

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.

bug#30610: clarify linux-mode usage from Lisp

[John Shahid]

Glenn Morris <rgm@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.

bug#30610: clarify linux-mode usage from Lisp

[Stefan Kangas]

close 30610 27.1
quit

John Shahid <jvshahid@gmail.com> writes:

>>From 04d261f836e5b000e8f6ed9e343417feaa8bc273 Mon Sep 17 00:00:00 2001
> From: John Shahid <jvshahid@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@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