bug#48058: tab-width's docstring

[Stefan Kangas <stefan@marxist.se>]

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