Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Date:   Sun, 12 Jun 2022 00:25:12 +0100
From:   Mauro Carvalho Chehab <mchehab@kernel.org>
To:     Akira Yokosawa <akiyks@gmail.com>
Cc:     Miguel Ojeda <miguel.ojeda.sandonis@gmail.com>,
        Jani Nikula <jani.nikula@linux.intel.com>,
        Jonathan Corbet <corbet@lwn.net>,
        Linux Doc Mailing List <linux-doc@vger.kernel.org>,
        "Maciej W. Rozycki" <macro@orcam.me.uk>,
        Miguel Ojeda <ojeda@kernel.org>,
        linux-kernel <linux-kernel@vger.kernel.org>
Subject: Re: [RFC PATCH 3/5] docs/doc-guide: Update guidelines for title
 adornments
Message-ID: <20220612002512.1150fc83@sal.lan>
In-Reply-To: <c25c29c7-28a6-65d4-8eb2-ac857894c1ba@gmail.com>
References: <dccb5233-7f4f-1be6-d1f4-bbe9f42f88e0@gmail.com>
        <732154bc-aa35-2326-2b64-87b6c4dd02e7@gmail.com>
        <871qvw2898.fsf@intel.com>
        <CANiq72n3MQnjenbQGBUKD+SqNzdGUyJW9zjTOVY4+6cKBRc9ig@mail.gmail.com>
        <c25c29c7-28a6-65d4-8eb2-ac857894c1ba@gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Precedence: bulk

Em Sat, 11 Jun 2022 12:15:54 +0900
Akira Yokosawa <akiyks@gmail.com> escreveu:

> On Fri, 10 Jun 2022 18:08:43 +0200,
> Miguel Ojeda wrote:
> > On Fri, Jun 10, 2022 at 11:11 AM Jani Nikula
> > <jani.nikula@linux.intel.com> wrote:  
> Thank Jani and Miguel for chiming in!
> As this is a RFC patch, I'm glad to have nice comments from both of you.
> 
> >>
> >> When I wrote the original guidelines, it was my subjective decision to
> >> steer towards using the same title adornment styles and ordering across
> >> the kernel documentation. I intentionally left out all the
> >> reStructuredText details about this, because the definitive
> >> documentation is the reStructuredText documentation we can refer to.
> >>
> >> While the "Nth level title" is a more precise description, I'm not sure
> >> it's actually helpful without describing how these levels should map to
> >> kernel documentation structure. (Not saying the original did that
> >> either, but then there wasn't much structure to speak of.)  
> I agree that we need to cover in doc-guide the way the kernel documentation
> is organized and managed.  Total lack of such documentation is kind of
> surprising to me.
> 
> > 
> > To give a bit of context: this patch followed from a question I asked
> > to Jonathan and Akira privately. Currently it is hard to tell the
> > "nesting level", and even worse, existing files are not consistent and
> > checking is not automated. Therefore, an easy way to handle this is to
> > request to follow the same pattern regardless of nesting across the
> > tree.

The thing is that there were *lots* of Kernel documents that were already
following ReST syntax, some requiring minor adjustments.

Yet, each one used its own way to indent the several levels. On most
of those, the indentation was:

	First
	=====

	Second
	------

Having to rewrite all tags at the entire document with no real gain,
while having a batch of thousands of documents left to be converted
from .txt to .rst was simply a waste of resources. At the documents
I converted myself, I just kept whatever level indentation it was
already there.

Going further, even now I would really prefer not needing to review
patches that are just changing the tags for each indentation level.
Again, this would be a waste of resources. I would very much like
to receive more patches adding kernel-doc documentation and ReST
changes to document the Kernel core APIs.

Now, for *new* documents, I agree that it makes sense to use a
standard way, at least up to level 3, like:

	=====
	First
	=====

	Second
	======

	Third
	-----

Which is quite intuitive to me. 

> >   
> >> Improving the documentation on documentation is great, but I think it's
> >> a bad sign when length of the notes and warnings on something far exceed
> >> the length of the thing being documented. The bulk of the text should be
> >> helpful enough for people to DTRT, while leaving out exhaustive
> >> descriptions of all the details that should just be references to
> >> reStructuredText documentation.  
> 
> So, I was not aware of such a hidden rule on what should _not_ be in
> doc-guide.  :-)
> In my opinion, RST documentation is not easy to follow especially for
> new contributors, and putting some useful tips somewhere in doc-guide
> would improve situation.
> 
> I agree with you that those notes and warning don't belong to guidelines.
> 
> Maybe add a section collecting RST tips and tricks mainly consisting
> of pointers to RST and docutils documentation.
> 
> > 
> > Perhaps we can move the rationale to the commit message, and keep only
> > the current rules in the document. What about something like:
> > 
> > """
> > Please stick to this relative order of adornments within each file
> > (i.e. regardless of nesting level across the kernel tree):
> > 
> >     1. ``=`` with overline.
> >     2. ``=``.
> >     3. ``-``.
> >     4. ``~``.

At least at the charset I use here, `~` is bigger than `-`. For me, it sounds
counter-intuitive to use it there... Personally, i prefer `^` for the
4th level.

Yet, the forth level (and the following ones) generally happen when someone
needs to add something to an already-existing document. I doubt anyone that
already works with ReST would ever look at the doc-guide if they need to 
add a 4th/5th/... level on an already existing documents.

So, IMO, it is pointless to define or expect that all docs would use the
same level markup after the third level.


> > For instance::
> > 
> >     =====
> >     First
> >     =====
> > 
> >     Second
> >     ======
> > 
> >     Third
> >     -----
> > 
> >     Fourth
> >     ~~~~~~
> > """  
> 
> I'm more inclined to keep "level"s in the example.

Agreed.

Regards,
Mauro