Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:18 as permitted sender) client-ip=2620:137:e000::1:18;
Message-ID: <0846c96d-62fa-555f-b0ab-1f5ec33fd5fb@gmail.com>
Date:   Sat, 21 May 2022 18:22:06 +0900
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101
 Thunderbird/91.8.1
Subject: Re: [PATCH] arm64: Unify vertical spacing in HWCAPS
Content-Language: en-US
To:     Bagas Sanjaya <bagasdotme@gmail.com>,
        =?UTF-8?Q?Martin_Li=c5=a1ka?= <mliska@suse.cz>
Cc:     linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        corbet@lwn.net, Catalin Marinas <catalin.marinas@arm.com>,
        Will Deacon <will@kernel.org>,
        linux-arm-kernel@lists.infradead.org
References: <4752814a-091c-9dd5-762c-6fd1a476c4bb@gmail.com>
 <e3921517-f903-3ad5-afa4-d7959051e5dd@suse.cz> <YoieFI7hdJPJW5qy@debian.me>
From:   Akira Yokosawa <akiyks@gmail.com>
In-Reply-To: <YoieFI7hdJPJW5qy@debian.me>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
Precedence: bulk

[+Cc: arm64 maintainers]
Hi Martin,

On 2022/05/21 17:08,
Bagas Sanjaya wrote:
> On Fri, May 20, 2022 at 04:01:33PM +0200, Martin Li=C5=A1ka wrote:
>> Promote headings by removing intermediate blank lines.
>>
>> Signed-off-by: Martin Liska <mliska@suse.cz>
>> ---
>>  Documentation/arm64/elf_hwcaps.rst | 23 -----------------------
>>  1 file changed, 23 deletions(-)
>>
>> diff --git a/Documentation/arm64/elf_hwcaps.rst b/Documentation/arm64/=
elf_hwcaps.rst
>> index a8f30963e550..1e79044f51a2 100644
>> --- a/Documentation/arm64/elf_hwcaps.rst
>> +++ b/Documentation/arm64/elf_hwcaps.rst
>> @@ -171,96 +171,73 @@ HWCAP_PACG
>>      Documentation/arm64/pointer-authentication.rst.
>> =20
>>  HWCAP2_DCPODP
>> -
>>      Functionality implied by ID_AA64ISAR1_EL1.DPB =3D=3D 0b0010.
>> =20
>>  HWCAP2_SVE2
>> -
>>      Functionality implied by ID_AA64ZFR0_EL1.SVEVer =3D=3D 0b0001.
>> =20
>>  HWCAP2_SVEAES
>> -
>>      Functionality implied by ID_AA64ZFR0_EL1.AES =3D=3D 0b0001.
>> =20
>>  HWCAP2_SVEPMULL
>> -
>>      Functionality implied by ID_AA64ZFR0_EL1.AES =3D=3D 0b0010.
>> =20
>>  HWCAP2_SVEBITPERM
>> -
>>      Functionality implied by ID_AA64ZFR0_EL1.BitPerm =3D=3D 0b0001.
>> =20
>>  HWCAP2_SVESHA3
>> -
>>      Functionality implied by ID_AA64ZFR0_EL1.SHA3 =3D=3D 0b0001.
>> =20
>>  HWCAP2_SVESM4
>> -
>>      Functionality implied by ID_AA64ZFR0_EL1.SM4 =3D=3D 0b0001.
>> =20
>>  HWCAP2_FLAGM2
>> -
>>      Functionality implied by ID_AA64ISAR0_EL1.TS =3D=3D 0b0010.
>> =20
>>  HWCAP2_FRINT
>> -
>>      Functionality implied by ID_AA64ISAR1_EL1.FRINTTS =3D=3D 0b0001.
>> =20
>>  HWCAP2_SVEI8MM
>> -
>>      Functionality implied by ID_AA64ZFR0_EL1.I8MM =3D=3D 0b0001.
>> =20
>>  HWCAP2_SVEF32MM
>> -
>>      Functionality implied by ID_AA64ZFR0_EL1.F32MM =3D=3D 0b0001.
>> =20
>>  HWCAP2_SVEF64MM
>> -
>>      Functionality implied by ID_AA64ZFR0_EL1.F64MM =3D=3D 0b0001.
>> =20
>>  HWCAP2_SVEBF16
>> -
>>      Functionality implied by ID_AA64ZFR0_EL1.BF16 =3D=3D 0b0001.
>> =20
>>  HWCAP2_I8MM
>> -
>>      Functionality implied by ID_AA64ISAR1_EL1.I8MM =3D=3D 0b0001.
>> =20
>>  HWCAP2_BF16
>> -
>>      Functionality implied by ID_AA64ISAR1_EL1.BF16 =3D=3D 0b0001.
>> =20
>>  HWCAP2_DGH
>> -
>>      Functionality implied by ID_AA64ISAR1_EL1.DGH =3D=3D 0b0001.
>> =20
>>  HWCAP2_RNG
>> -
>>      Functionality implied by ID_AA64ISAR0_EL1.RNDR =3D=3D 0b0001.
>> =20
>>  HWCAP2_BTI
>> -
>>      Functionality implied by ID_AA64PFR0_EL1.BT =3D=3D 0b0001.
>> =20
>>  HWCAP2_MTE
>> -
>>      Functionality implied by ID_AA64PFR1_EL1.MTE =3D=3D 0b0010, as de=
scribed
>>      by Documentation/arm64/memory-tagging-extension.rst.
>> =20
>>  HWCAP2_ECV
>> -
>>      Functionality implied by ID_AA64MMFR0_EL1.ECV =3D=3D 0b0001.
>> =20
>>  HWCAP2_AFP
>> -
>>      Functionality implied by ID_AA64MFR1_EL1.AFP =3D=3D 0b0001.
>> =20
>>  HWCAP2_RPRES
>> -
>>      Functionality implied by ID_AA64ISAR2_EL1.RPRES =3D=3D 0b0001.
>> =20
>>  HWCAP2_MTE3
>> -
>>      Functionality implied by ID_AA64PFR1_EL1.MTE =3D=3D 0b0011, as de=
scribed
>>      by Documentation/arm64/memory-tagging-extension.rst.
>> =20
>> --=20
>> 2.36.1
>>
>=20
> Hi,
>=20
> Sorry for misunderstanding of this topic on my reply at [1].
>=20
> After applying this patch and doing htmldocs build, I see the HTML
> diff below.

Hey Bagas, please don't speak in HTML diffs.
Let's talk about ReST formatting.

So, the earlier part of the lists read:

----
HWCAP_FP
    Functionality implied by ID_AA64PFR0_EL1.FP =3D=3D 0b0000.

HWCAP_ASIMD
    Functionality implied by ID_AA64PFR0_EL1.AdvSIMD =3D=3D 0b0000.

HWCAP_EVTSTRM
    The generic timer is configured to generate events at a frequency of
    approximately 10KHz.
[...]
-----

I see that what Martin wants is the consistency of the format of the list=
s.
I think the change is quite reasonable.

The list construct is called "Definition lists" in ReST. See:
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#defini=
tion-lists

This construct makes the defined terms be rendered in bolder
face.  On the other hand, similar looking existing lists:

----
HWCAP2_DCPODP

    Functionality implied by ID_AA64ISAR1_EL1.DPB =3D=3D 0b0010.

HWCAP2_SVE2

    Functionality implied by ID_AA64ZFR0_EL1.SVEVer =3D=3D 0b0001.

[...]
----

are not recognized as "Definition lists" and rendered differently.
Actually speaking, they are not in any list format.

So my suggestion of the title would be:

  "docs/arm64: elf_hwcaps: Unify HWCAP lists as description lists"

[...]
> Also, when submitting next iterations of your patch series, don't forge=
t
> to pass -v <number> to git-format-patch(1) so that the patch subject
> prefix contains the correct version numbers. I gave that advice because=

> I don't see that this patch is sent as v2 of [2].
>=20
> CCing Akira to help reviewing.
>=20
> [1]: https://lore.kernel.org/linux-doc/4752814a-091c-9dd5-762c-6fd1a476=
c4bb@gmail.com/
> [2]: https://lore.kernel.org/linux-doc/b95b3128-f010-dcba-1f6a-1a85dd2d=
20a5@suse.cz/
>=20

Yeah, please post the next version as a v3.

Also, please note that this document belongs to the ARM64 PORT
(AARCH64 ARCHITECTURE) subsystem.
So please consult the entry in MAINTAINERS and prepare a
patch against its tree at:

T:	git git://git.kernel.org/pub/scm/linux/kernel/git/arm64/linux.git

and CC to the maintainers and the list of the subsystem.

        Thanks, Akira