Sender: codeagain@codeagain.dev
Date:   Sun, 12 Mar 2023 18:57:27 -0300
From:   Bru Moreira-Guedes <codeagain@codeagain.dev>
To:     Jonathan Corbet <corbet@lwn.net>
Cc:     linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        Patch Watchbox <patch-reply@codeagain.dev>
Subject: Re: [PATCH] coding-style.rst: indentation: Clarify tabs text
Message-ID: <20230312215727.xjs4jusdzpnfhjd3@guidai>
References: <20230228222035.k227xb3okt2lbksn@guidai>
 <87356gpjqv.fsf@meer.lwn.net>
MIME-Version: 1.0
Content-Type: multipart/signed; micalg=pgp-sha256;
        protocol="application/pgp-signature"; boundary="vkxuay2ar4gkqjoa"
Content-Disposition: inline
In-Reply-To: <87356gpjqv.fsf@meer.lwn.net>
Precedence: bulk

--vkxuay2ar4gkqjoa
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

Hello, Jonathan!

(Resending for I accidentally didn't copy the lists)

On Tue, Mar 07, 2023 at 10:13:44AM -0700, Jonathan Corbet wrote:
> Bru Moreira-Guedes <codeagain@codeagain.dev> writes:
>
> > It might be misleading, especially for some autistic readers for whom
> > English is not the first language and whose tendency to interpret things
> > more literally might be present (i.e., my very own self).

Perhaps I clearly made a poor description of the problem this patch
solves. I'll address it in details when I respond to your points. I
could certainly improve it for a v2.

> >
> > The present patch clarifies the tabs text on such aspects.
> >
> > Signed-off-by: Bru Moreira-Guedes <codeagain@codeagain.dev>
> > ---
> >  Documentation/process/coding-style.rst | 14 ++++++++------
> >  1 file changed, 8 insertions(+), 6 deletions(-)
> >
> > diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
> > index 007e49ef6cec..9a0205fa7ed3 100644
> > --- a/Documentation/process/coding-style.rst
> > +++ b/Documentation/process/coding-style.rst
> > @@ -18,23 +18,25 @@ Anyway, here goes:
> >  1) Indentation
> >  --------------
> >
> > -Tabs are 8 characters, and thus indentations are also 8 characters.
> > -There are heretic movements that try to make indentations 4 (or even 2!)
> > -characters deep, and that is akin to trying to define the value of PI to
> > -be 3.
> > +The Linux Kernel uses the TAB character for indentation, as in the K&R
> > +style. Tabs are meant to be viewed as 8-characters, and thus
> > +indentations are meant to be seen as 8 characters as well. There are
> > +heretic movements that try to use spaces for indentation, or make tabs
> > +viewed as 4 (or even 2!) characters, and that is akin to trying to
> > +define the value of PI to be 5.
>
> I guess I really don't see how this kind of tweaking helps things; this
> text has stood for a couple of decades or so without evident
> misunderstandings.

Well, there was my own misunderstanding that motivated this patch :-}
so, there is at least one evidenced case. Anyway, I think this is more
of an improvement to make the text accessible for everyone, including
autistic readers who might have a tendency towards literal
interpretation. Just like me :D

I don't actually think we would have a way to find out if everyone else
who read this text throughout all those decades got it properly.
Historically, the linux kernel hasn't been overall a much accessible
project in a general sense. I think this kind of change is important if
we want to move to the right direction.

> ...and I'm totally mystified as to why we've redefined pi from 3 to 5?

Ohhh, never mind this part, it shouldn't be here. At first I was
undecided on whether to change it or not. I actually thought I had
removed it. It just came to my mind that the value of pi is a constant,
yet its representation is always bound to a certain precision level.
Since the text didn't use decimal places, assuming no decimal precision
the pi is actually near 3. Since the text appears to be trying to show
an example of something "absurd", I think another value could be more
appropriate. But yea, this change would not affect anyone and I think it
shouldn't be done.

> >
> > -Now, some people will claim that having 8-character indentations makes
> > +Now, some people will claim that viewint 8-character tab indentations makes
>
> Adding typos doesn't really help either.

Sorry, I clearly had a poor review of the changed text (and I failed to
setup spell-checking on checkpatch.pl). Yet Bagas did an excellent job
in the other thread pointing me out all the details I missed. I'll be
doing a v2 soon!

Best,
Bru Moreira-Guedes
they/them


--vkxuay2ar4gkqjoa
Content-Type: application/pgp-signature; name="signature.asc"

-----BEGIN PGP SIGNATURE-----

iHUEABYIAB0WIQQTUrsHCxGmQ5vyKRAZtd3tyEY2kgUCZA5KxwAKCRAZtd3tyEY2
knx6AQC4IrNGSbbmCnvUGreWoxw8zI51sGbmnP5/QW1HhysmvgEA0uRDJ1PFc8lw
c03rv5iS2gh053jNGIjb8lvOM+2O3gM=
=5Q7e
-----END PGP SIGNATURE-----

--vkxuay2ar4gkqjoa--