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
