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

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

[Drew Adams]

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''

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

[Eli Zaretskii]

tags 48511 wontfix
close 48511
thanks

> From: Drew Adams <drew.adams@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.

bug#48511: [External] : Re: bug#48511: 26.3; Doc string of `global-display-line-numbers-mode'

[Drew Adams]

> 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