Received-SPF: pass (google.com: domain of linux-kernel+bounces-89958-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:45d1:ec00::1 as permitted sender) client-ip=2604:1380:45d1:ec00::1;
Message-ID: <ef93a03b-d43e-44e7-bb55-17b46d86104c@gmail.com>
Date: Mon, 4 Mar 2024 10:14:59 +0900
Precedence: bulk
MIME-Version: 1.0
User-Agent: Mozilla Thunderbird
Subject: Re: [PATCH v2 3/3] docs: submit-checklist: change to autonumbered
 lists
To: Jonathan Corbet <corbet@lwn.net>, lukas.bulwahn@gmail.com
Cc: jani.nikula@intel.com, kernel-janitors@vger.kernel.org,
 linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
 rdunlap@infradead.org, workflows@vger.kernel.org,
 Akira Yokosawa <akiyks@gmail.com>
References: <20240229030743.9125-4-lukas.bulwahn@gmail.com>
 <8df0c587-8f5b-4523-89d7-dc458ab2c1df@gmail.com>
 <8734t7z4vs.fsf@meer.lwn.net>
Content-Language: en-US
From: Akira Yokosawa <akiyks@gmail.com>
In-Reply-To: <8734t7z4vs.fsf@meer.lwn.net>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit

On Sun, 03 Mar 2024 08:55:51 -0700, Jonathan Corbet wrote:
> Akira Yokosawa <akiyks@gmail.com> writes:
> 
>>> -1) If you use a facility then #include the file that defines/declares
>>> +#. If you use a facility then #include the file that defines/declares
>>>     that facility.  Don't depend on other header files pulling in ones
>>>     that you use.
>>
>> Wait.  This will render the list starting from:
>>
>>     1. If you use ...
>>
>> In patch 1/1, you didn't change the ")".
>>
>> It was Jani who suggested "#.", but "#)" would work just fine.
> 
> So I'm a little confused.  Is the objection that it renders the number
> as "1." rather than "1)"?  That doesn't seem like the biggest of deals,
> somehow, but am I missing something?
> 

I said at the top of my reply:

> I might be nitpicking too much, but let me go ahead...

, and my point here was to let Lukas aware of the variation of auto-
numbering patterns.  I don't object the change from "1." to "1)" if
that change is intended and explained in the changelog.

HTML builder recognizes "1)", but renders it as "1.", while
LATEX builder renders it as "1)".

> A bigger complaint I might raise is that auto-numbering restarts the
> enumeration in each subsection, so we have a lot of steps #1, which is a
> definite change from before.

+1

> That, of course, can be fixed by giving an explicit starting number in
> each subsection, partially defeating the point of the change in the
> first place.

Right.

> 
> I honestly have to wonder: does this document need the enumerated list
> at all?  We don't refer to the numbers anywhere, so I don't think there
> is much useful information there.  How about just using regular bulleted
> lists instead?

That would make a lot of sense.
Auto-numbered enumerated lists look mostly the same as bulleted lists
in the source.

No strong opinion, but I'd respect Randy's preference of not applying
this change.

        Thanks, Akira

> 
> That said, I don't have strong feelings one way or the other, and can
> certainly apply it as-is if that's the consensus on what we should do.
> 
> Thanks,
> 
> jon