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] [day] [month] [year] [list]

Date: Mon, 4 Mar 2024 10:14:59 +0900
From: Akira Yokosawa <akiyks@...il.com>
To: Jonathan Corbet <corbet@....net>, 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

On Sun, 03 Mar 2024 08:55:51 -0700, Jonathan Corbet wrote:
> 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?
> 

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