GNU bug report logs - #48511
26.3; Doc string of `global-display-line-numbers-mode'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 48511 in the body.
You can then email your comments to 48511 AT debbugs.gnu.org in the normal way.

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

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

From: Drew Adams <drew.adams <at> oracle.com>
To: "bug-gnu-emacs <at> gnu.org" <bug-gnu-emacs <at> gnu.org>
Subject: 26.3; Doc string of `global-display-line-numbers-mode'
Date: Tue, 18 May 2021 22:25:28 +0000

The Emacs manual, node `Display Custom' says this:

  The command 'M-x display-line-numbers-mode' provides a convenient way
  to turn on display of line numbers.  This mode has a globalized variant,
  'global-display-line-numbers-mode'.  The user option
  'display-line-numbers-type' controls which sub-mode of line-number
  display, described above, will these modes activate.
                            ^^^^^^^^^^^^^^^^^^^^^^^^^

That's good.  It talks about option `display-line-numbers-type' right
where it talks about _both_ the global and buffer-local modes.  And
it says "these modes", so it's clear that the option applies to both.

And the doc string of `display-line-numbers-mode' tells you about
`display-line-numbers-type'.

But the doc string of `global-display-line-numbers-mode' says nothing
about it.  Yes, it has a cross-ref to the doc string of
`display-line-numbers-mode', but users won't necessarily follow that.
The point is that if users have no knowledge of that option then they
will likely try to do something like what this user did:

 https://emacs.stackexchange.com/q/64898/105

That user understandably figured that using `setq-default' would take
care of setting the type globally (using option `display-line-numbers').  

Alas, for some reason this isn't the case, and instead we have this
other option for that.  But to think of setting the default (global)
behavior you need to know about the existence that `*-type' option.

Please add the same or similar text about this option to the doc string
of the global mode function as you have in the doc string of the local
mode.

Another reason to do this is that that option isn't autoloaded, so
`C-h v' won't show it until `display-line-numbers.el[c]' has been
loaded.

Also, the underlined text above should be changed to "these modes will
activate".  This is an English problem (though many people will
understand the text as it's written now).

In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32)
 of 2019-08-29
Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd
Windowing system distributor `Microsoft Corp.', version 10.0.19041
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 48511 <at> debbugs.gnu.org
Subject: Re: bug#48511: 26.3; Doc string of `global-display-line-numbers-mode'
Date: Wed, 19 May 2021 15:04:05 +0300

tags 48511 wontfix
close 48511
thanks

> From: Drew Adams <drew.adams <at> oracle.com>
> Date: Tue, 18 May 2021 22:25:28 +0000
> 
> The Emacs manual, node `Display Custom' says this:
> 
>   The command 'M-x display-line-numbers-mode' provides a convenient way
>   to turn on display of line numbers.  This mode has a globalized variant,
>   'global-display-line-numbers-mode'.  The user option
>   'display-line-numbers-type' controls which sub-mode of line-number
>   display, described above, will these modes activate.
>                             ^^^^^^^^^^^^^^^^^^^^^^^^^
> [...]
> 
> Please add the same or similar text about this option to the doc string
> of the global mode function as you have in the doc string of the local
> mode.

I don't agree that we should bloat the doc strings (and thus the Emacs
memory footprint) because some user failed to follow a link that
already exists.  That's a slippery slope I'd rather we don't take.

Closing.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: "48511 <at> debbugs.gnu.org" <48511 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#48511: 26.3; Doc string of
 `global-display-line-numbers-mode'
Date: Thu, 20 May 2021 22:09:00 +0000

> Closing.

You don't even want to correct the English?

   X controls which Y will these modes activate

should be

   X controls which Y these modes will activate

Previous Next

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