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
| ||
|
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
Powered by blists - more mailing lists