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

[Joe Stringer]

On Fri, Nov 4, 2022 at 4:10 PM Jonathan Corbet <corbet@xxxxxxx> wrote:
>
> Joe Stringer <joe@xxxxxxxxxxxxx> writes:
>
> > Resending, this time without HTML.
> >
> > On Fri, Nov 4, 2022 at 2:31 AM Bagas Sanjaya <bagasdotme@xxxxxxxxx> 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.

Ah yikes, I just searched down for an example of how to sketch up a
table and followed the first example I saw. I guess this is more the
syntax you'd expect?

https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#tables

> > 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.

Sorry, I switched to a new email address and inadvertently enabled
HTML formatting, so my initial posting ended up rejected and my
re-post snipped the important part. This response was intended as a
response to the question around the formatting of the commit message
content:

> What about just writing the pointer ("See commit 3a08c2fd7634 ("bpf: LRU List")")
instead?

My thoughts were that the commit message describes the high level +
algorithm pretty well and that text compliments the diagram quite
well. But if there's some preferred processing I should perform on the
text to format it well in the docs, I can do that.

Cheers,
Joe