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