bug#48058: tab-width's docstring

[Gustavo Barros]

Hi Eli,

On Tue, 27 Apr 2021 at 10:53, Eli Zaretskii <eliz@gnu.org> wrote:

> > 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).

So indeed, I might be missing something.  But I really cannot combine 
what the docstring says and what the option actually does, so I'll try 
to explain why I think that's the case.  And I'll either learn something 
or, if my confusion may potentially affect other people, leave the 
docstring clearer somehow.

The docstring explicitly says `tab-width' "controls the display width of 
a TAB character, and not the size of an indentation step".  And btw, I 
know the actual behavior of indentation is subject to major-mode 
differences.  And also of some user options.

Let's say `emacs-lisp-mode', and let's say I've `indent-tabs-mode' set 
to nil.  Calling `tab-to-tab-stop' will actually insert 8 spaces in my 
buffer, as per the default `tab-width'.  If `tab-always-indent' is nil, 
this also extends to `indent-for-tab-command'.  There is no "TAB 
character" involved, and also no issue about what is its "display 
width".  As far as I understand it, what `tab-width' is determining is 
precisely the "indentation step".  Or am I getting this wrong?

As far as I get, what `tab-width' is doing it is being used as the 
default width of an indentation step regardless of whether this 
indentation is done with a TAB character or with spaces.  And, of 
course, this also matches the display width of the TAB character.  But 
the docstring reads to me as explicitly denying the first role.

Does this make sense?  Or, at least, could I convey why I am confused by 
the docstring?

Best regards,
Gustavo.