bug#48058: tab-width's docstring

[Eli Zaretskii <eliz@gnu.org>]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Thu, 29 Apr 2021 17:53:27 -0500
> Cc: 48058@debbugs.gnu.org
> 
>    DEFVAR_PER_BUFFER ("tab-width", &BVAR (current_buffer, tab_width),
>  		     Qintegerp,
>  		     doc: /* Distance between tab stops (for display of tab characters), in columns.
> -NOTE: This controls the display width of a TAB character, and not
> -the size of an indentation step.
> -This should be an integer greater than zero.  */);
> +This controls the display width of a TAB character and should be an
> +integer greater than zero.
> +
> +In some major modes, this is also used to control the size of an
> +indentation step.  However, this is not always the case.  See the
> +major mode documentation for the exact details \\[describe-mode].  */);

I don't think the user will find anything about this in the
documentation of the major mode.  Did you see anything useful about
this in the doc string of any major mode or in what "C-h m" displays
for that mode?  I tried two very popular modes (ELisp and C) and
didn't see anything pertinent.

I propose the following text instead:

  Distance between tab stops (for display of tab characters), in columns.

  This controls the width of a TAB character on display.
  The value should be a positive integer.
  Note that this variable doesn't necessarily affect the size of the
  indentation step, but if the major mode's indentation facility
  inserts one or more TAB characters, this variable will affect the
  indentation step as well, even if `indent-tabs-mode' is non-nil.