Clarify display-line-numbers width in manual

Clarify display-line-numbers width in manual

[Pedro Andres Aranda Gutierrez]

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

HI

I recently had to migrate to display-line-numbers-mode. It was hard to find
what I wanted in the manual at first glance, which was how to set the width
of the line numbers to fixed width. It was somehow buried in a paragraph
along with other succinct explanations for other variables.

Here is a proposal to highlight the variable in the manual

diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index a4040d9..ee76e77 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -1882,6 +1882,12 @@ Display Custom
 non-@code{nil}.  It has no effect when set to zero, or when line
 numbers are not absolute.

+@vindex display-line-numbers-width
+Set the value of @code{display-line-numbers-width} to fix the width
+of the line number. Make sure it is large enough for the largest files
+you expect to edit (e.g. @code{4} would allow up to @code{9999} lines
+to be displayed correctly)
+
 @vindex display-line-numbers-width-start
 @vindex display-line-numbers-grow-only
 @vindex display-line-numbers-width

Best, /Pedro A.
-- 
Fragen sind nicht da um beantwortet zu werden,
Fragen sind da um gestellt zu werden
Georg Kreisler

[-- Attachment #2: Type: text/html, Size: 1516 bytes --]

Re: Clarify display-line-numbers width in manual

[Eli Zaretskii]

> From: Pedro Andres Aranda Gutierrez <paaguti@gmail.com>
> Date: Sat, 17 Oct 2020 07:30:49 +0200
> 
> I recently had to migrate to display-line-numbers-mode. It was hard to find what I wanted in the manual at
> first glance, which was how to set the width of the line numbers to fixed width. It was somehow buried in a
> paragraph along with other succinct explanations for other variables.
> 
> Here is a proposal to highlight the variable in the manual
> 
> diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
> index a4040d9..ee76e77 100644
> --- a/doc/emacs/display.texi
> +++ b/doc/emacs/display.texi
> @@ -1882,6 +1882,12 @@ Display Custom
>  non-@code{nil}.  It has no effect when set to zero, or when line
>  numbers are not absolute.
>  
> +@vindex display-line-numbers-width
> +Set the value of @code{display-line-numbers-width} to fix the width
> +of the line number. Make sure it is large enough for the largest files
> +you expect to edit (e.g. @code{4} would allow up to @code{9999} lines
> +to be displayed correctly)

Thanks.  However, I don't understand the motivation well enough to
judge the patch, or to propose some different text to take care of
this issue.  You say "to fix the width" and "to be displayed
correctly", and that hints on, or could be interpreted as, saying that
the default values yield incorrect display.  Which is not what I see
here.

So please tell what display problems you tried to fix by setting
display-line-numbers-width in your configuration, and what information
you tried to find in the manual about that.

In any case, you copied the @vindex entry to your text, but left the
original one intact, which would have the effect of having 2 identical
index entries pointing to very close locations in the text, something
that is undesirable.

Re: Clarify display-line-numbers width in manual

[Pedro Andres Aranda Gutierrez]

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

Hi,

well, I was on the old linum package and now that emacs26 is widely
available and I started to get a weird
behaviour on emacs27, the time seemed to have come to move on to
display-line-numbers.
One of the things I'm only to used to change is that the line number field
has a fixed width (ie it doesn't depend
on the lines being displayed). And going through the manual, it was not
obvious at all how to do that.

s/fix the width/set the width/g

And let me think how to reword the 'display correctly' sentence

Best, /PA

On Sat, 17 Oct 2020 at 10:49, Eli Zaretskii <eliz@gnu.org> wrote:

> > From: Pedro Andres Aranda Gutierrez <paaguti@gmail.com>
> > Date: Sat, 17 Oct 2020 07:30:49 +0200
> >
> > I recently had to migrate to display-line-numbers-mode. It was hard to
> find what I wanted in the manual at
> > first glance, which was how to set the width of the line numbers to
> fixed width. It was somehow buried in a
> > paragraph along with other succinct explanations for other variables.
> >
> > Here is a proposal to highlight the variable in the manual
> >
> > diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
> > index a4040d9..ee76e77 100644
> > --- a/doc/emacs/display.texi
> > +++ b/doc/emacs/display.texi
> > @@ -1882,6 +1882,12 @@ Display Custom
> >  non-@code{nil}.  It has no effect when set to zero, or when line
> >  numbers are not absolute.
> >
> > +@vindex display-line-numbers-width
> > +Set the value of @code{display-line-numbers-width} to fix the width
> > +of the line number. Make sure it is large enough for the largest files
> > +you expect to edit (e.g. @code{4} would allow up to @code{9999} lines
> > +to be displayed correctly)
>
> Thanks.  However, I don't understand the motivation well enough to
> judge the patch, or to propose some different text to take care of
> this issue.  You say "to fix the width" and "to be displayed
> correctly", and that hints on, or could be interpreted as, saying that
> the default values yield incorrect display.  Which is not what I see
> here.
>
> So please tell what display problems you tried to fix by setting
> display-line-numbers-width in your configuration, and what information
> you tried to find in the manual about that.
>
> In any case, you copied the @vindex entry to your text, but left the
> original one intact, which would have the effect of having 2 identical
> index entries pointing to very close locations in the text, something
> that is undesirable.
>


-- 
Fragen sind nicht da um beantwortet zu werden,
Fragen sind da um gestellt zu werden
Georg Kreisler

[-- Attachment #2: Type: text/html, Size: 3433 bytes --]