linux-kernel - Re: [PATCH v2 3/3] docs: submit-checklist: change to autonumbered lists

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <8734t7z4vs.fsf@meer.lwn.net>
Date: Sun, 03 Mar 2024 08:55:51 -0700
From: Jonathan Corbet <corbet@....net>
To: Akira Yokosawa <akiyks@...il.com>, lukas.bulwahn@...il.com
Cc: jani.nikula@...el.com, kernel-janitors@...r.kernel.org,
 linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
 rdunlap@...radead.org, workflows@...r.kernel.org, Akira Yokosawa
 <akiyks@...il.com>
Subject: Re: [PATCH v2 3/3] docs: submit-checklist: change to autonumbered
 lists

Akira Yokosawa <akiyks@...il.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?

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.

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.

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 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