bug#48058: tab-width's docstring

[Gustavo Barros <gusbrs.2016@gmail.com>]

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.