bug#48058: tab-width's docstring

bug#48058: tab-width's docstring

[Gustavo Barros]

Hi All,

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

Am I missing something?  Or is this docstring the remnant of a previous 
change which was left behind?

Best regards,
Gustavo.

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

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.

bug#48058: tab-width's docstring

[Eli Zaretskii]

> From: Gustavo Barros <gusbrs.2016@gmail.com>
> Cc: 48058@debbugs.gnu.org
> Date: Tue, 27 Apr 2021 11:40:18 -0300
> 
> 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?

This is major mode dependent.  Try the same in C mode, for example,
and you will see the difference.  The function that indents the line
is specific to the major mode.  If you want to understand why you see
what you see in emacs-lisp-mode, look at lisp-indent-line.

But even in emacs-lisp-mode, what did you expect to happen instead?
(indent-tabs-mode, btw, just uses spaces instead of TABs, but it still
inserts the amount of spaces equivalent to a TAB where otherwise a TAB
would have been inserted.)

bug#48058: tab-width's docstring

[Gustavo Barros]

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

>> From: Gustavo Barros <gusbrs.2016@gmail.com>
>> Cc: 48058@debbugs.gnu.org
>> Date: Tue, 27 Apr 2021 11:40:18 -0300
>> 
>> 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?
>
> This is major mode dependent.  Try the same in C mode, for example,
> and you will see the difference.  The function that indents the line
> is specific to the major mode.  If you want to understand why you see
> what you see in emacs-lisp-mode, look at lisp-indent-line.
>
> But even in emacs-lisp-mode, what did you expect to happen instead?
> (indent-tabs-mode, btw, just uses spaces instead of TABs, but it still
> inserts the amount of spaces equivalent to a TAB where otherwise a TAB
> would have been inserted.)

I didn't expect anything different to happen.  It is just that 
`tab-width' is determining more than just the "display width of the TAB 
character": if you (or the major-mode for you) are indenting with spaces 
the content of the buffer is different according to `tab-width', it not 
just a matter of "display".

But I see your point, and perhaps the docstring is clearer to someone 
more seasoned than myself, and avoids other pitfalls along the way which 
I do not even see.  Hopefully, it will feel just as clear to me someday. 
;-)

Thanks for answering, and feel free to close.

Best regards,
Gustavo.

bug#48058: tab-width's docstring

[Eli Zaretskii]

> From: Gustavo Barros <gusbrs.2016@gmail.com>
> Cc: 48058@debbugs.gnu.org
> Date: Tue, 27 Apr 2021 12:14:50 -0300
> 
> I didn't expect anything different to happen.  It is just that 
> `tab-width' is determining more than just the "display width of the TAB 
> character": if you (or the major-mode for you) are indenting with spaces 
> the content of the buffer is different according to `tab-width', it not 
> just a matter of "display".
> 
> But I see your point, and perhaps the docstring is clearer to someone 
> more seasoned than myself, and avoids other pitfalls along the way which 
> I do not even see.  Hopefully, it will feel just as clear to me someday. 
> ;-)

Fair enough, let's see if there are other opinions about this.

bug#48058: tab-width's docstring

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> I didn't expect anything different to happen.  It is just that
>> `tab-width' is determining more than just the "display width of the TAB
>> character": if you (or the major-mode for you) are indenting with spaces
>> the content of the buffer is different according to `tab-width', it not
>> just a matter of "display".
>>
>> But I see your point, and perhaps the docstring is clearer to someone
>> more seasoned than myself, and avoids other pitfalls along the way which
>> I do not even see.  Hopefully, it will feel just as clear to me someday.
>> ;-)
>
> Fair enough, let's see if there are other opinions about this.

I agree that the docstring is somewhat confusing, as it seems to rule
out that this variable is ever used to control indentation.  But some
major modes do precisely that.

Perhaps we could change the docstring note along the lines of:

    NOTE: Some major modes use this variable to determine an indentation
    step, but Emacs itself only uses this to display the width of a TAB
    character.

Would something like that make sense?

---

Also the last line of the docstring is odd to me:

    This should be an integer greater than zero.

Should the "should" be changed to "must"?

bug#48058: tab-width's docstring

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Thu, 29 Apr 2021 12:05:39 -0500
> Cc: Gustavo Barros <gusbrs.2016@gmail.com>, 48058@debbugs.gnu.org
> 
> I agree that the docstring is somewhat confusing, as it seems to rule
> out that this variable is ever used to control indentation.  But some
> major modes do precisely that.
> 
> Perhaps we could change the docstring note along the lines of:
> 
>     NOTE: Some major modes use this variable to determine an indentation
>     step, but Emacs itself only uses this to display the width of a TAB
>     character.
> 
> Would something like that make sense?

Something like that, yes.  Perhaps just making the original text less
definitive will do as well.

> Also the last line of the docstring is odd to me:
> 
>     This should be an integer greater than zero.
> 
> Should the "should" be changed to "must"?

Those two are equivalent in this context.

bug#48058: tab-width's docstring

[Gustavo Barros]

On Thu, 29 Apr 2021 at 14:35, Eli Zaretskii <eliz@gnu.org> wrote:

>> From: Stefan Kangas <stefan@marxist.se>
>> Date: Thu, 29 Apr 2021 12:05:39 -0500
>> Cc: Gustavo Barros <gusbrs.2016@gmail.com>, 48058@debbugs.gnu.org
>> 
>> I agree that the docstring is somewhat confusing, as it seems to rule
>> out that this variable is ever used to control indentation.  But some
>> major modes do precisely that.
>> 
>> Perhaps we could change the docstring note along the lines of:
>> 
>>     NOTE: Some major modes use this variable to determine an 
>>     indentation
>>     step, but Emacs itself only uses this to display the width of a 
>>     TAB
>>     character.
>> 
>> Would something like that make sense?
>
> Something like that, yes.  Perhaps just making the original text less
> definitive will do as well.
>

Just chiming in to say I'm following the discussion attentively, but 
have nothing to add.  Both Stefan's and Eli's suggestions look like 
improvements to me.  And I'll be happy with what you come up with.

Best regards,
Gustavo.

bug#48058: tab-width's docstring

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 734 bytes --]

tags 48058 + patch
thanks

Gustavo Barros <gusbrs.2016@gmail.com> writes:

>>> Perhaps we could change the docstring note along the lines of:
>>>
>>>     NOTE: Some major modes use this variable to determine an
>>>     indentation
>>>     step, but Emacs itself only uses this to display the width of a
>>>     TAB
>>>     character.
>>>
>>> Would something like that make sense?
>>
>> Something like that, yes.  Perhaps just making the original text less
>> definitive will do as well.
>
> Just chiming in to say I'm following the discussion attentively, but
> have nothing to add.  Both Stefan's and Eli's suggestions look like
> improvements to me.  And I'll be happy with what you come up with.

How does the attached patch look?

[-- Attachment #2: 0001-Clarify-docstring-of-tab-width-variable.patch --]
[-- Type: text/x-diff, Size: 1408 bytes --]

From 522b4588df225d6e825c2ce3c3d81144bd7e3bff Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefan@marxist.se>
Date: Fri, 30 Apr 2021 00:38:42 +0200
Subject: [PATCH] Clarify docstring of tab-width variable

* src/buffer.c (syms_of_buffer) <tab_width>: Doc fix; clarify that
this variable is used by some (but not all) major modes to control an
indentation step.  (Bug#48058)
---
 src/buffer.c | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/src/buffer.c b/src/buffer.c
index 8e33162989..0540ebf034 100644
--- a/src/buffer.c
+++ b/src/buffer.c
@@ -5666,9 +5666,12 @@ syms_of_buffer (void)
   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].  */);
 
   DEFVAR_PER_BUFFER ("ctl-arrow", &BVAR (current_buffer, ctl_arrow), Qnil,
 		     doc: /* Non-nil means display control chars with uparrow.
-- 
2.30.2

bug#48058: tab-width's docstring

[Gustavo Barros]

Hi Stefan,

On Thu, 29 Apr 2021 at 19:53, Stefan Kangas <stefan@marxist.se> wrote:

> tags 48058 + patch
> thanks
>
> Gustavo Barros <gusbrs.2016@gmail.com> writes:
>
>>>> Perhaps we could change the docstring note along the lines of:
>>>>
>>>>     NOTE: Some major modes use this variable to determine an
>>>>     indentation
>>>>     step, but Emacs itself only uses this to display the width of a
>>>>     TAB
>>>>     character.
>>>>
>>>> Would something like that make sense?
>>>
>>> Something like that, yes.  Perhaps just making the original text 
>>> less
>>> definitive will do as well.
>>
>> Just chiming in to say I'm following the discussion attentively, but
>> have nothing to add.  Both Stefan's and Eli's suggestions look like
>> improvements to me.  And I'll be happy with what you come up with.
>
> How does the attached patch look?

Thanks, I do think it is an improvement, and had granted that in my 
previous message.  And I also think the role I can play in this 
discussion is to provide some perspective on why it is difficult to get 
this docstring right for someone less acquainted with the fine prints of 
how indentation works.  With that in mind, I tried to come up with 
something which would make it more clear to one such person.  I hope I 
didn't get it wrong in so doing.  It is the following:

"`tab-width' controls the display width of a TAB character and the width 
of a tab step if it uses spaces instead of TAB characters, according to 
user options and major-mode settings.  In most major modes the 
indentation step is derived from the langage's semantics and is 
independent of `tab-width', but some major-modes use it to control the 
size of an indentation step."

Three things I hope to have added there which are not in the current 
docstring or in your patch.  It is not just major-mode, user options 
influence too how `tab-width' is used.  It is also not just 
"indentation", since a manual tab added by `tab-to-stop' or by 
`indent-for-tab-command' (if `tab-always-indent' is nil) will use 
`tab-width'.  It is also not just "display of TAB character width", 
since `tab-width' will determine the number of spaces inserted if 
`indent-tabs-mode' is nil.  And I grant I may be wrong in any number of 
these three things.  But if I'm not, I do think they deserve mention.

Again, this is not a "proposal", this is just what I miss there that I 
believe makes it hard to get what `tab-width' does (if you don't already 
know).  And I think one of the things I failed to understand correctly, 
even when I opened this report, and the discussion with Eli helped me 
get a little better, is the term "indentation step".  If I understand it 
better now, it is aimed at referring only to "major-mode specific 
indentation of a semantic character".  Thus I included the term "tab 
step" as opposed to "indentation step", meaning a manually added "tab" 
(character or corresponding spaces).  This may seem obvious to most on 
this list, but I missed my step (pun intended) right there.  And I 
cannot even claim noobness (though I'll probably be guilty as charged).

Best regards,
Gustavo.

bug#48058: tab-width's docstring

[Eli Zaretskii]

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

bug#48058: tab-width's docstring

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

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

Perhaps we could divide the last sentence up to make it easier to read?

    Note that this variable doesn't necessarily affect the size of the
    indentation step.  However, if the major mode's indentation facility
    normally inserts one or more TAB characters, this variable will
    affect the indentation step as well, even if `indent-tabs-mode' is
    non-nil.

Otherwise LGTM, please install.

bug#48058: tab-width's docstring

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Fri, 30 Apr 2021 05:20:12 -0500
> Cc: gusbrs.2016@gmail.com, 48058@debbugs.gnu.org
> 
>     Note that this variable doesn't necessarily affect the size of the
>     indentation step.  However, if the major mode's indentation facility
>     normally inserts one or more TAB characters, this variable will
>     affect the indentation step as well, even if `indent-tabs-mode' is
>     non-nil.
> 
> Otherwise LGTM, please install.

Thanks, done (with one minor deviation: the "normally" part is not
useful here).

bug#48058: tab-width's docstring

[Gustavo Barros]

On Fri, 30 Apr 2021 at 07:49, Eli Zaretskii <eliz@gnu.org> wrote:

>> From: Stefan Kangas <stefan@marxist.se>
>> Date: Fri, 30 Apr 2021 05:20:12 -0500
>> Cc: gusbrs.2016@gmail.com, 48058@debbugs.gnu.org
>> 
>>     Note that this variable doesn't necessarily affect the size of 
>>     the
>>     indentation step.  However, if the major mode's indentation 
>>     facility
>>     normally inserts one or more TAB characters, this variable will
>>     affect the indentation step as well, even if `indent-tabs-mode' 
>>     is
>>     non-nil.
>> 
>> Otherwise LGTM, please install.
>
> Thanks, done (with one minor deviation: the "normally" part is not
> useful here).

Eli and Stefan, thank you very much.

Best regards,
Gustavo.