bug#48058: tab-width's docstring

[Eli Zaretskii]

> From: Gustavo Barros <gusbrs.2016@gmail.com>
> Date: Tue, 27 Apr 2021 10:11:30 -0300
> 
> In Emacs 27.2 the docstring for `tab-width' reads:
> 
> "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."
> 
> But this seems to contradict to the ubiquitous role in actual 
> indentation the option currently plays.  It is used by `insert-tab' 
> directly.  `tab-to-tab-stop' uses it if `tab-stop-list' is nil, as it is 
> by default.  `indent-relative' may use `tab-to-tab-stop'.  And, through 
> `indent-relative' and `insert-tab', `tab-width' also affects 
> `indent-for-tab-command'.

Can you explain where you see the contradiction, exactly?

If the indentation command (which is subject to major-mode
differences, btw) actually inserts one or more TAB characters, then
those TABs will look on display according to tab-width, of course, and
that's not in any contradiction to what the doc string says.  The doc
string says something different: that an indentation step is not
necessarily the number of columns that tab-width says, because a major
mode can decide that it indents with spaces instead, for example
(texinfo-mode, for example, does precisely that).