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;
Message-ID: <c25c29c7-28a6-65d4-8eb2-ac857894c1ba@gmail.com>
Date:   Sat, 11 Jun 2022 12:15:54 +0900
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101
 Thunderbird/91.9.1
From:   Akira Yokosawa <akiyks@gmail.com>
Subject: Re: [RFC PATCH 3/5] docs/doc-guide: Update guidelines for title
 adornments
To:     Miguel Ojeda <miguel.ojeda.sandonis@gmail.com>,
        Jani Nikula <jani.nikula@linux.intel.com>
Cc:     Jonathan Corbet <corbet@lwn.net>,
        Linux Doc Mailing List <linux-doc@vger.kernel.org>,
        Mauro Carvalho Chehab <mchehab@kernel.org>,
        "Maciej W. Rozycki" <macro@orcam.me.uk>,
        Miguel Ojeda <ojeda@kernel.org>,
        linux-kernel <linux-kernel@vger.kernel.org>
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>
Content-Language: en-US
In-Reply-To: <CANiq72n3MQnjenbQGBUKD+SqNzdGUyJW9zjTOVY4+6cKBRc9ig@mail.gmail.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk

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.
> 
>> 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. ``~``.
> 
> For instance::
> 
>     =====
>     First
>     =====
> 
>     Second
>     ======
> 
>     Third
>     -----
> 
>     Fourth
>     ~~~~~~
> """

I'm more inclined to keep "level"s in the example.
Without them, a new contributor might be confused to use those
adornments exactly in that order, for example:

    ==============
    Document title
    ==============

    Chapter A
    =========

    Section A.1
    -----------

    Section A.2
    ~~~~~~~~~~~

    Section A.3
    ???????????

Unlikely, but possible...

Anyway, I'll post a v2 for your further comments.
Might take a while.

        Thanks, Akira
> 
> Cheers,
> Miguel