linux-kernel - Re: [PATCH bpf-next v2] docs/bpf: Add LRU internals description and graph

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: <87fseyqpso.fsf@meer.lwn.net>
Date:   Fri, 04 Nov 2022 17:10:31 -0600
From:   Jonathan Corbet <corbet@....net>
To:     Joe Stringer <joe@...valent.com>,
        Bagas Sanjaya <bagasdotme@...il.com>
Cc:     bpf@...r.kernel.org, linux-doc@...r.kernel.org,
        linux-kernel@...r.kernel.org, ast@...nel.org, martin.lau@...ux.dev
Subject: Re: [PATCH bpf-next v2] docs/bpf: Add LRU internals description and
 graph

Joe Stringer <joe@...valent.com> writes:

> Resending, this time without HTML.
>
> On Fri, Nov 4, 2022 at 2:31 AM Bagas Sanjaya <bagasdotme@...il.com> wrote:
>>
>> Shouldn't the table be written in reST table syntax instead?
>
> This table follows the syntax outlined in
> https://docs.kernel.org/doc-guide/sphinx.html#list-tables . Is that
> document not up to date?

That document, right where you linked, says:

	The list-table formats can be useful for tables that are not
	easily laid out in the usual Sphinx ASCII-art formats. These
	formats are nearly impossible for readers of the plain-text
	documents to understand, though, and should be avoided in the
	absence of a strong justification for their use.

The list-table formats exist for a reason, and sometimes they can't
really be avoided, but they do impose a heavy readability cost on the
plain-text files.

> I'm happy to do this, but several of the diagram boxes will reference
> terms like rotation, shrinking etc without explaining what they are. I
> think it's a net negative to readability if this text is not included
> with the diagram. If you think the commit formatting is a bit over the
> top, I could maybe just remove the decoration and embed the content
> directly in the doc? On my first attempt at sketching this up, it just
> felt a bit weird for me to submit that text directly if Martin was the
> author of the text. But I could figure something out for that if
> that's the preferred approach.

I don't quite understand this comment; I don't think anybody is asking
you to take information out?  Just to use one of the other table formats
if you can.

>> Since it references the same figure, just say "See the figure above for more
>> details".
>
> The figure is rendered visually in the docs without the corresponding
> node names, so developers would need to look at either the dot source
> or maybe the SVG source though that's arguably a little less readable.
> The suggested phrasing to see the figure doesn't sound very useful to
> me since the simple reader's interpretation would be to look directly
> at the render rather than the source. This last sentence was intended
> as a helpful way for developers to find the path to the corresponding
> document, but if you think that is too much detail then I could also
> just drop this last sentence. Thoughts?

That sentence is fine, I wouldn't mess with it.

Thanks,

jon