From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Gustavo Barros Newsgroups: gmane.emacs.bugs Subject: bug#48058: tab-width's docstring Date: Thu, 29 Apr 2021 21:44:26 -0300 Message-ID: <87r1issis5.fsf@gmail.com> References: <87a6pj50u6.fsf@gmail.com> <83eeevj0kt.fsf@gnu.org> <87wnsnkcz1.fsf@gmail.com> <8335vbixea.fsf@gnu.org> <87tunrkbdi.fsf@gmail.com> <83y2d3hhfe.fsf@gnu.org> <83pmydc7u6.fsf@gnu.org> <874kfo26gt.fsf@gmail.com> Mime-Version: 1.0 Content-Type: text/plain; format=flowed Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="35157"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: mu4e 1.4.15; emacs 27.2 Cc: 48058@debbugs.gnu.org To: Stefan Kangas Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Fri Apr 30 02:45:27 2021 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1lcHHa-00093K-FW for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 30 Apr 2021 02:45:26 +0200 Original-Received: from localhost ([::1]:44480 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1lcHHZ-0003Mb-8w for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 29 Apr 2021 20:45:25 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:57260) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lcHHB-0003M8-Rw for bug-gnu-emacs@gnu.org; Thu, 29 Apr 2021 20:45:01 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:45612) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1lcHHB-0006Ay-Km for bug-gnu-emacs@gnu.org; Thu, 29 Apr 2021 20:45:01 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1lcHHB-0002ih-JZ for bug-gnu-emacs@gnu.org; Thu, 29 Apr 2021 20:45:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Gustavo Barros Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 30 Apr 2021 00:45:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 48058 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 48058-submit@debbugs.gnu.org id=B48058.161974348110415 (code B ref 48058); Fri, 30 Apr 2021 00:45:01 +0000 Original-Received: (at 48058) by debbugs.gnu.org; 30 Apr 2021 00:44:41 +0000 Original-Received: from localhost ([127.0.0.1]:57158 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lcHGq-0002hu-Qc for submit@debbugs.gnu.org; Thu, 29 Apr 2021 20:44:41 -0400 Original-Received: from mail-qk1-f182.google.com ([209.85.222.182]:34558) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lcHGo-0002hh-LW for 48058@debbugs.gnu.org; Thu, 29 Apr 2021 20:44:39 -0400 Original-Received: by mail-qk1-f182.google.com with SMTP id q127so9985851qkb.1 for <48058@debbugs.gnu.org>; Thu, 29 Apr 2021 17:44:38 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:references:user-agent:from:to:cc:subject:in-reply-to :message-id:date:mime-version; bh=ta6wZbOnY1QuUtAHwh8lh1cvA3j3joL+P3bMFK4Dhr4=; b=OAg3WW+7Wy0Y4Xf2k/oG9eQA1njFY13wIeSimASD/v0gwS6OfURuhg7WQJ1KNmkBLf kXA6q3rmJ2zTXPdan29yZsme5E8/y8SnC6CPoH7Bd+MBYGleRBARPdHn2a41s64VfDaD L1dV/AATzmQPZTe0nULrFETG/v+T5JsnZ0j6eWUpNRkSzthuX/EhVHltkLEEnMwEo8hf j90t5ooFBMjUuhLyt6vwcUle7kRQ79tB4SufNEw+zv+WIC6G4JMBeK8ek3SvUKf2GVg/ xDODyi57/uaK17A4t3Gonotl7CiNILsZQPjHQOEeDYteZXFIlf+BixzUiB2pBlj+2Rc5 9FlQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:references:user-agent:from:to:cc:subject :in-reply-to:message-id:date:mime-version; bh=ta6wZbOnY1QuUtAHwh8lh1cvA3j3joL+P3bMFK4Dhr4=; b=IoRHymq55hTmBn55XjxLJk97dvmohFQcWaVMY6o/rlV3CVM1HYKHZWWBL45Zsyh2tZ ICrpPMxJCUAPKVOjHPw0VsC54Q4+NRqE/3ChF9aOzjhbvTfxs7IiQCNenBLhtM72fhmE v68EQE5Un/gDwtsn4Nt1nh95UCkBitgh3UR18l2a1Nn6c1UfUwyWM1IquIDgmTUap+3f PYP1DVVgE46/kVzkU2LlScue/3PP172q62qrx8dED+3deuLm+QY5tjp7ZgqxShuSsWaX czuGvkEdTKgILwpp9mrEgFPxuqx/Sl8R98NNxq/K6YsuzMdnESFyNu+qCfPUJXMgq9fP hh5g== X-Gm-Message-State: AOAM530MvHPsscLvOGmorqWyPFEDuP3dgJ6j1YaumGtwJHSiSzc3MSJ9 Wf3L2JHEdB4UQpjAtxYd2yg6oVihaiwKIQ== X-Google-Smtp-Source: ABdhPJzHT+TE/X2Tu1LFUmG3tMFYIh3PV66463zGY2uY8uxs5i3EvS85+Ar8gcG2V2AmRqLd7CYfrg== X-Received: by 2002:ae9:ef88:: with SMTP id d130mr2576672qkg.107.1619743472770; Thu, 29 Apr 2021 17:44:32 -0700 (PDT) Original-Received: from gusbrs-laptop ([154.21.22.220]) by smtp.gmail.com with ESMTPSA id v3sm218054qkb.124.2021.04.29.17.44.30 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 29 Apr 2021 17:44:31 -0700 (PDT) In-reply-to: X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:205219 Archived-At: Hi Stefan, On Thu, 29 Apr 2021 at 19:53, Stefan Kangas wrote: > tags 48058 + patch > thanks > > Gustavo Barros 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.