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

[Jonathan Corbet <corbet@lwn.net>]

Joe Stringer <joe@isovalent.com> writes:

> Resending, this time without HTML.
>
> On Fri, Nov 4, 2022 at 2:31 AM Bagas Sanjaya <bagasdotme@gmail.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