From:   "Fabio M. De Francesco" <fmdefrancesco@gmail.com>
To:     error27@gmail.com, Sumitra Sharma <sumitraartsy@gmail.com>
Cc:     GR-Linux-NIC-Dev@marvell.com, coiby.xu@gmail.com,
        gregkh@linuxfoundation.org, linux-kernel@vger.kernel.org,
        linux-staging@lists.linux.dev, manishc@marvell.com,
        netdev@vger.kernel.org, outreachy@lists.linux.dev
Subject: Re: [PATCH] Staging: qlge: Remove parenthesis around single condition
Date:   Sat, 11 Mar 2023 21:35:41 +0100
Message-ID: <1713523.QkHrqEjB74@suse>
In-Reply-To: <20230311144318.GC14247@ubuntu>
References: <20230311144318.GC14247@ubuntu>
MIME-Version: 1.0
Content-Transfer-Encoding: 7Bit
Content-Type: text/plain; charset="us-ascii"
Precedence: bulk

On sabato 11 marzo 2023 15:43:18 CET Sumitra Sharma wrote:
> Hi Dan,
> 
> Your suggestion for correcting the indentation to
> "[tab][tab][space][space][space][space](i ==." conflicts with the
> statement "Outside of comments, documentation and except in Kconfig,
> spaces are never used for indentation" written in
> https://elixir.bootlin.com/linux/latest/source/Documentation/process/coding-style.rst
>

I just saw that you use to read .rst files. Attention!
These are source files from which human readable documentation is made.

They may contain directives which don't show a large part of the content you 
are interested in, which is only included when you run "make html", "make pdf" 
and similar commands.

Obviously, I'm talking about something that is _not_ related to your patch or 
this thread. I'm just concerned that candidates won't be able to find the 
information they're looking for and thus miss out on important information 
that Ira and I have asked candidates to study (if they're interested in 
applying to our project). 

In any case, the study of a certain number of pages of the Kernel 
documentation is always necessary, whatever project one wishes to undertake.

To better understand what I'm talking about, take the Highmem documentation as 
an example and compare the .rst file and the .html file. You will understand 
why I am strongly encouraging you and all other applicants not to use 
elixir.bootlin.com for study.

Please compare the content (or at least the number of sections and lines) of 
following .rst file at

https://elixir.bootlin.com/linux/v6.3-rc1/source/Documentation/mm/highmem.rst

with the human readable counterpart at 

https://docs.kernel.org/mm/highmem.html

Can you see how many information you may miss by reading an .rst file without 
any knowledge of its syntax?

Thanks,

Fabio

PS: I don't know why you went to the documentation source files. I see no 
reason other than the need to work on patches for the source document.

I'd like to invite you to patch the style guide that Dan suggested to you in 
this same thread.

But I'm not asking you to spend time on that patch during this contribution 
period because you still have a lot to do before the period expires.

If you want, you could take care of that patch after the contribution period 
has ended and while you are waiting for the outcome of the selection. If so, 
study the syntax of the .rst format carefully.

In the "real" kernel (I mean anywhere outside of drivers/staging), you might 
not always get the custom help of the same kind you can count on here. 
However, those who intend to go further, regardless of the current project, 
sooner or later will have to face the world outside :-)

>
> However, If you still recommend to correct the indentation in the manner
> "[tab][tab][space][space][space][space](i ==." Should I create a
> patch for the same?
> 
> Regards,
> 
> Sumitra