netdev - Re: [PATCH net-next v2 01/11] tools/net/ynl-gen-rst: Use bullet lists for attribute-set entries

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 for Android: free password hash cracker in your pocket

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

Date: Tue, 12 Dec 2023 11:27:18 +0000
From: Donald Hunter <donald.hunter@...il.com>
To: Jakub Kicinski <kuba@...nel.org>
Cc: netdev@...r.kernel.org,  "David S. Miller" <davem@...emloft.net>,  Eric
 Dumazet <edumazet@...gle.com>,  Paolo Abeni <pabeni@...hat.com>,  Jonathan
 Corbet <corbet@....net>,  linux-doc@...r.kernel.org,  Jacob Keller
 <jacob.e.keller@...el.com>,  donald.hunter@...hat.com, Breno Leitao
 <leitao@...ian.org>
Subject: Re: [PATCH net-next v2 01/11] tools/net/ynl-gen-rst: Use bullet
 lists for attribute-set entries

Jakub Kicinski <kuba@...nel.org> writes:

> On Mon, 11 Dec 2023 16:40:29 +0000 Donald Hunter wrote:
>> The generated .rst for attribute-sets currently uses a sub-sub-heading
>> for each individual attribute. Change this to use a bullet list the
>> attributes in an attribute-set. It is more compact and readable.
>
> This is on purpose, we want to be able to link to the attributes.
> And AFAIU we can only link to headings.
>
> The documentation for attrs is currently a bit sparse so the docs 
> end up looking awkward. But that's a problem with people not writing
> enough doc comments, not with the render, innit? :(

Okay, then I think we need to try and improve the formatting. Currently
h3 and h4 both have font-size: 130% and the attribute headings get
rendered in bold so they stand out more than the attribute-set headings
they are under. I suggest:

 - Removing the bold markup from the attribute headings
 - Changing h4 to font-size: 110% in sphinx-static/custom.css

That improves things a bit but I feel that the attribute-set headings
still get a bit lost. Not sure if there is anything we can do about
that. The devlink spec is a fairly extreme example because it has a lot
of subset definitions that look especially bleak.