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

Previous Next

Full log

View this message in rfc822 format

From: Drew Adams <drew.adams <at> oracle.com>
To: 48511 <at> debbugs.gnu.org
Subject: bug#48511: 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''

Previous Next

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