bug#37120: [PATCH] Prefer display-line-numbers over linum in docs and custom

bug#37120: [PATCH] Prefer display-line-numbers over linum in docs and custom

[Stefan Kangas]

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

NEWS.26 says:

'linum-mode' and all similar packages are henceforth becoming obsolete.
Users and developers are encouraged to switch to this new feature
[i.e. display-line-numbers-mode] instead.

This patch updates the FAQ to recommend display-line-numbers-mode over
linum-mode.  It also changes one defcustom in progmodes in the same
way.

WDYT?  And, if it looks good, should it go to the master branch or emacs-26?

Thanks,
Stefan Kangas

PS. I'm not sure if linum.el should also be moved into lisp/obsolete/
or if that's premature for 27.1.

[-- Attachment #2: 0001-Prefer-display-line-numbers-over-linum-in-docs-and-o.patch --]
[-- Type: text/x-patch, Size: 1729 bytes --]

From 5b5d923611f0d3b344d1da93f112a99e58e47d60 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Sat, 1 Jun 2019 01:40:11 +0200
Subject: [PATCH] Prefer display-line-numbers over linum in docs and one
 defcustom

* doc/misc/efaq.texi: Replace linum with display-line-numbers-mode.
* lisp/progmodes/prog-mode.el (prog-mode-hook): Replace linum-mode
with display-line-numbers-mode in :options.
---
 doc/misc/efaq.texi          | 2 +-
 lisp/progmodes/prog-mode.el | 3 ++-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/doc/misc/efaq.texi b/doc/misc/efaq.texi
index 8fd3bf3a45..2548673b5b 100644
--- a/doc/misc/efaq.texi
+++ b/doc/misc/efaq.texi
@@ -1687,7 +1687,7 @@ Displaying the current line or column
 this variable.
 
 @cindex Set number capability in @code{vi} emulators
-The @samp{linum} package (distributed with Emacs since version 23.1)
+@samp{display-line-numbers-mode} (added to Emacs in version 26.1)
 displays line numbers in the left margin, like the ``set number''
 capability of @code{vi}.  The packages @samp{setnu} and
 @samp{wb-line-number} (not distributed with Emacs) also implement this
diff --git a/lisp/progmodes/prog-mode.el b/lisp/progmodes/prog-mode.el
index cb39e62265..8d3513bad3 100644
--- a/lisp/progmodes/prog-mode.el
+++ b/lisp/progmodes/prog-mode.el
@@ -39,7 +39,8 @@ prog-mode
 (defcustom prog-mode-hook nil
   "Normal hook run when entering programming modes."
   :type 'hook
-  :options '(flyspell-prog-mode abbrev-mode flymake-mode linum-mode
+  :options '(flyspell-prog-mode abbrev-mode flymake-mode
+                                display-line-numbers-mode
                                 prettify-symbols-mode)
   :group 'prog-mode)
 
-- 
2.20.1

bug#37120: [PATCH] Prefer display-line-numbers over linum in docs and custom

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Tue, 20 Aug 2019 19:26:02 +0200
> 
> NEWS.26 says:
> 
> 'linum-mode' and all similar packages are henceforth becoming obsolete.
> Users and developers are encouraged to switch to this new feature
> [i.e. display-line-numbers-mode] instead.
> 
> This patch updates the FAQ to recommend display-line-numbers-mode over
> linum-mode.  It also changes one defcustom in progmodes in the same
> way.

Thanks, but see the comments below.

> WDYT?  And, if it looks good, should it go to the master branch or emacs-26?

It should go to master.

> PS. I'm not sure if linum.el should also be moved into lisp/obsolete/
> or if that's premature for 27.1.

I think it's still premature.

> --- a/doc/misc/efaq.texi
> +++ b/doc/misc/efaq.texi
> @@ -1687,7 +1687,7 @@ Displaying the current line or column
>  this variable.
>  
>  @cindex Set number capability in @code{vi} emulators
> -The @samp{linum} package (distributed with Emacs since version 23.1)
> +@samp{display-line-numbers-mode} (added to Emacs in version 26.1)
>  displays line numbers in the left margin, like the ``set number''
>  capability of @code{vi}.  The packages @samp{setnu} and

This is incorrect: display-line-numbers-mode doesn't use the display
margin (linum.el did).

>  @samp{wb-line-number} (not distributed with Emacs) also implement this
> diff --git a/lisp/progmodes/prog-mode.el b/lisp/progmodes/prog-mode.el
> index cb39e62265..8d3513bad3 100644
> --- a/lisp/progmodes/prog-mode.el
> +++ b/lisp/progmodes/prog-mode.el
> @@ -39,7 +39,8 @@ prog-mode
>  (defcustom prog-mode-hook nil
>    "Normal hook run when entering programming modes."
>    :type 'hook
> -  :options '(flyspell-prog-mode abbrev-mode flymake-mode linum-mode
> +  :options '(flyspell-prog-mode abbrev-mode flymake-mode
> +                                display-line-numbers-mode
>                                  prettify-symbols-mode)

Hmm... is it reasonable to run prog-mode-hook just because someone
turns on line numbers?  It sounds too drastic to me.

bug#37120: [PATCH] Prefer display-line-numbers over linum in docs and custom

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> Thanks, but see the comments below.

Thanks for reviewing this patch.

> > --- a/doc/misc/efaq.texi
> > +++ b/doc/misc/efaq.texi
> > @@ -1687,7 +1687,7 @@ Displaying the current line or column
> >  this variable.
> >
> >  @cindex Set number capability in @code{vi} emulators
> > -The @samp{linum} package (distributed with Emacs since version 23.1)
> > +@samp{display-line-numbers-mode} (added to Emacs in version 26.1)
> >  displays line numbers in the left margin, like the ``set number''
> >  capability of @code{vi}.  The packages @samp{setnu} and
>
> This is incorrect: display-line-numbers-mode doesn't use the display
> margin (linum.el did).

Would "displays line numbers on the left side of the current window"
be more precise?

> > diff --git a/lisp/progmodes/prog-mode.el b/lisp/progmodes/prog-mode.el
> > index cb39e62265..8d3513bad3 100644
> > --- a/lisp/progmodes/prog-mode.el
> > +++ b/lisp/progmodes/prog-mode.el
> > @@ -39,7 +39,8 @@ prog-mode
> >  (defcustom prog-mode-hook nil
> >    "Normal hook run when entering programming modes."
> >    :type 'hook
> > -  :options '(flyspell-prog-mode abbrev-mode flymake-mode linum-mode
> > +  :options '(flyspell-prog-mode abbrev-mode flymake-mode
> > +                                display-line-numbers-mode
> >                                  prettify-symbols-mode)
>
> Hmm... is it reasonable to run prog-mode-hook just because someone
> turns on line numbers?  It sounds too drastic to me.

I'm not sure I understand what you mean.  I thought that this just
means that when running M-x customize-option RET prog-mode-hook RET we
show display-line-numbers-mode instead of linum-mode as an option.  Is
there something I'm missing here?

Best regards,
Stefan Kangas

bug#37120: [PATCH] Prefer display-line-numbers over linum in docs and custom

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Tue, 20 Aug 2019 20:18:49 +0200
> Cc: 37120@debbugs.gnu.org
> 
> > >  @cindex Set number capability in @code{vi} emulators
> > > -The @samp{linum} package (distributed with Emacs since version 23.1)
> > > +@samp{display-line-numbers-mode} (added to Emacs in version 26.1)
> > >  displays line numbers in the left margin, like the ``set number''
> > >  capability of @code{vi}.  The packages @samp{setnu} and
> >
> > This is incorrect: display-line-numbers-mode doesn't use the display
> > margin (linum.el did).
> 
> Would "displays line numbers on the left side of the current window"
> be more precise?

I'd prefer "displays line numbers in the text area, before each line".
("Left side" is not entirely accurate, because in R2L paragraphs the
numbers are displayed on the right.)

> > >  (defcustom prog-mode-hook nil
> > >    "Normal hook run when entering programming modes."
> > >    :type 'hook
> > > -  :options '(flyspell-prog-mode abbrev-mode flymake-mode linum-mode
> > > +  :options '(flyspell-prog-mode abbrev-mode flymake-mode
> > > +                                display-line-numbers-mode
> > >                                  prettify-symbols-mode)
> >
> > Hmm... is it reasonable to run prog-mode-hook just because someone
> > turns on line numbers?  It sounds too drastic to me.
> 
> I'm not sure I understand what you mean.  I thought that this just
> means that when running M-x customize-option RET prog-mode-hook RET we
> show display-line-numbers-mode instead of linum-mode as an option.

My point is that neither linum-mode nor display-line-numbers-mode are
for program sources.  But that's not a very important point, so maybe
ignore me.

bug#37120: [PATCH] Prefer display-line-numbers over linum in docs and custom

[Stefan Kangas]

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

Eli Zaretskii <eliz@gnu.org> writes:

> I'd prefer "displays line numbers in the text area, before each line".

In the attached patch, the suggested text is changed as you suggest
and extended with details on how to use it.  WDYT?

> ("Left side" is not entirely accurate, because in R2L paragraphs the
> numbers are displayed on the right.)

Good point.

> My point is that neither linum-mode nor display-line-numbers-mode are
> for program sources.  But that's not a very important point, so maybe
> ignore me.

OK, thanks for clarifying.

Best regards,
Stefan Kangas

[-- Attachment #2: 0001-Prefer-display-line-numbers-over-linum-in-docs-and-o.patch --]
[-- Type: text/x-patch, Size: 2679 bytes --]

From 0e76a8238b684860eb75f049dffd0c7b4c978272 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Sat, 1 Jun 2019 01:40:11 +0200
Subject: [PATCH] Prefer display-line-numbers over linum in docs and one
 defcustom

* doc/misc/efaq.texi: Replace linum with display-line-numbers-mode.
* lisp/progmodes/prog-mode.el (prog-mode-hook): Replace linum-mode
with display-line-numbers-mode in :options.
---
 doc/misc/efaq.texi          | 19 ++++++++++++++-----
 lisp/progmodes/prog-mode.el |  3 ++-
 2 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/doc/misc/efaq.texi b/doc/misc/efaq.texi
index 8fd3bf3a45..67fc05c810 100644
--- a/doc/misc/efaq.texi
+++ b/doc/misc/efaq.texi
@@ -1687,11 +1687,20 @@ Displaying the current line or column
 this variable.
 
 @cindex Set number capability in @code{vi} emulators
-The @samp{linum} package (distributed with Emacs since version 23.1)
-displays line numbers in the left margin, like the ``set number''
-capability of @code{vi}.  The packages @samp{setnu} and
-@samp{wb-line-number} (not distributed with Emacs) also implement this
-feature.
+The @samp{display-line-numbers} package (added to Emacs in version
+26.1) displays line numbers in the text area, before each line, like
+the ``set number'' capability of @code{vi}.  Customize the
+buffer-local variable 'display-line-numbers' to activate this optional
+display.  Alternatively, you can use the 'display-line-numbers-mode'
+minor mode or the global 'global-display-line-numbers-mode'.  When
+using these modes, customize 'display-line-numbers-type' with the same
+value as you would use with 'display-line-numbers'.
+
+There is also the @samp{linum} package (distributed with Emacs since
+version 23.1) which will henceforth become obsolete.  Users and
+developers are encouraged to use @samp{display-line-numbers} instead.
+The packages @samp{setnu} and @samp{wb-line-number} (not distributed
+with Emacs) also implement this feature.
 
 @node Displaying the current file name in the titlebar
 @section How can I modify the titlebar to contain the current file name?
diff --git a/lisp/progmodes/prog-mode.el b/lisp/progmodes/prog-mode.el
index cb39e62265..8d3513bad3 100644
--- a/lisp/progmodes/prog-mode.el
+++ b/lisp/progmodes/prog-mode.el
@@ -39,7 +39,8 @@ prog-mode
 (defcustom prog-mode-hook nil
   "Normal hook run when entering programming modes."
   :type 'hook
-  :options '(flyspell-prog-mode abbrev-mode flymake-mode linum-mode
+  :options '(flyspell-prog-mode abbrev-mode flymake-mode
+                                display-line-numbers-mode
                                 prettify-symbols-mode)
   :group 'prog-mode)
 
-- 
2.20.1

bug#37120: [PATCH] Prefer display-line-numbers over linum in docs and custom

[Robert Pluim]

>>>>> On Thu, 22 Aug 2019 14:29:58 +0200, Stefan Kangas <stefan@marxist.se> said:

    Stefan> From 0e76a8238b684860eb75f049dffd0c7b4c978272 Mon Sep 17 00:00:00 2001
    Stefan> From: Stefan Kangas <stefankangas@gmail.com>
    Stefan> Date: Sat, 1 Jun 2019 01:40:11 +0200
    Stefan> Subject: [PATCH] Prefer display-line-numbers over linum in docs and one
    Stefan>  defcustom

    Stefan> * doc/misc/efaq.texi: Replace linum with display-line-numbers-mode.
    Stefan> * lisp/progmodes/prog-mode.el (prog-mode-hook): Replace linum-mode
    Stefan> with display-line-numbers-mode in :options.
    Stefan> ---
    Stefan>  doc/misc/efaq.texi          | 19 ++++++++++++++-----
    Stefan>  lisp/progmodes/prog-mode.el |  3 ++-
    Stefan>  2 files changed, 16 insertions(+), 6 deletions(-)

    Stefan> diff --git a/doc/misc/efaq.texi b/doc/misc/efaq.texi
    Stefan> index 8fd3bf3a45..67fc05c810 100644
    Stefan> --- a/doc/misc/efaq.texi
    Stefan> +++ b/doc/misc/efaq.texi
    Stefan> @@ -1687,11 +1687,20 @@ Displaying the current line or column
    Stefan>  this variable.
 
    Stefan>  @cindex Set number capability in @code{vi} emulators
    Stefan> -The @samp{linum} package (distributed with Emacs since version 23.1)
    Stefan> -displays line numbers in the left margin, like the ``set number''
    Stefan> -capability of @code{vi}.  The packages @samp{setnu} and
    Stefan> -@samp{wb-line-number} (not distributed with Emacs) also implement this
    Stefan> -feature.
    Stefan> +The @samp{display-line-numbers} package (added to Emacs in version
    Stefan> +26.1) displays line numbers in the text area, before each line, like
    Stefan> +the ``set number'' capability of @code{vi}.  Customize
    Stefan> the

@samp around 'set number'? (although it was like that before your changes).

    Stefan> +buffer-local variable 'display-line-numbers' to activate this optional
    Stefan> +display.  Alternatively, you can use the 'display-line-numbers-mode'
    Stefan> +minor mode or the global 'global-display-line-numbers-mode'.  When
    Stefan> +using these modes, customize 'display-line-numbers-type' with the same
    Stefan> +value as you would use with 'display-line-numbers'.
    Stefan> +

All these variables/command should use @code{} rather than explicit quotes, I
think.

Robert

bug#37120: [PATCH] Prefer display-line-numbers over linum in docs and custom

[Stefan Kangas]

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

Robert Pluim <rpluim@gmail.com> writes:

> All these variables/command should use @code{} rather than explicit quotes, I
> think.

Oops, you are correct of course.  Please find attached a patch fixing that.

Thanks,
Stefan Kangas

[-- Attachment #2: 0001-Prefer-display-line-numbers-over-linum-in-docs-and-o.patch --]
[-- Type: text/x-patch, Size: 2714 bytes --]

From f41ce5b462234d1561c98290fb1e84cb8f7bfb45 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Sat, 1 Jun 2019 01:40:11 +0200
Subject: [PATCH] Prefer display-line-numbers over linum in docs and one
 defcustom

* doc/misc/efaq.texi: Replace linum with display-line-numbers.
* lisp/progmodes/prog-mode.el (prog-mode-hook): Replace linum-mode
with display-line-numbers-mode in :options.  (Bug#37120)
---
 doc/misc/efaq.texi          | 20 +++++++++++++++-----
 lisp/progmodes/prog-mode.el |  3 ++-
 2 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/doc/misc/efaq.texi b/doc/misc/efaq.texi
index 8fd3bf3a45..df212e43b9 100644
--- a/doc/misc/efaq.texi
+++ b/doc/misc/efaq.texi
@@ -1687,11 +1687,21 @@ Displaying the current line or column
 this variable.
 
 @cindex Set number capability in @code{vi} emulators
-The @samp{linum} package (distributed with Emacs since version 23.1)
-displays line numbers in the left margin, like the ``set number''
-capability of @code{vi}.  The packages @samp{setnu} and
-@samp{wb-line-number} (not distributed with Emacs) also implement this
-feature.
+The @samp{display-line-numbers} package (added to Emacs in version
+26.1) displays line numbers in the text area, before each line, like
+the ``set number'' capability of @samp{vi}.  Customize the
+buffer-local variable @code{display-line-numbers} to activate this
+optional display.  Alternatively, you can use the
+@code{display-line-numbers-mode} minor mode or the global
+@code{global-display-line-numbers-mode}.  When using these modes,
+customize @code{display-line-numbers-type} with the same value as you
+would use with @code{display-line-numbers}.
+
+There is also the @samp{linum} package (distributed with Emacs since
+version 23.1) which will henceforth become obsolete.  Users and
+developers are encouraged to use @samp{display-line-numbers} instead.
+The packages @samp{setnu} and @samp{wb-line-number} (not distributed
+with Emacs) also implement this feature.
 
 @node Displaying the current file name in the titlebar
 @section How can I modify the titlebar to contain the current file name?
diff --git a/lisp/progmodes/prog-mode.el b/lisp/progmodes/prog-mode.el
index cb39e62265..8d3513bad3 100644
--- a/lisp/progmodes/prog-mode.el
+++ b/lisp/progmodes/prog-mode.el
@@ -39,7 +39,8 @@ prog-mode
 (defcustom prog-mode-hook nil
   "Normal hook run when entering programming modes."
   :type 'hook
-  :options '(flyspell-prog-mode abbrev-mode flymake-mode linum-mode
+  :options '(flyspell-prog-mode abbrev-mode flymake-mode
+                                display-line-numbers-mode
                                 prettify-symbols-mode)
   :group 'prog-mode)
 
-- 
2.20.1

bug#37120: [PATCH] Prefer display-line-numbers over linum in docs and custom

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Thu, 22 Aug 2019 15:27:53 +0200
> Cc: Eli Zaretskii <eliz@gnu.org>, 37120@debbugs.gnu.org
> 
> > All these variables/command should use @code{} rather than explicit quotes, I
> > think.
> 
> Oops, you are correct of course.  Please find attached a patch fixing that.

LGTM, thanks.

bug#37120: [PATCH] Prefer display-line-numbers over linum in docs and custom

[Stefan Kangas]

close 37120 27.1
quit

Eli Zaretskii <eliz@gnu.org> writes:

> LGTM, thanks.

Thanks; pushed to master as commit 3ef6849b45.

Best regards,
Stefan Kangas