On Mon, 9 Mar 2026 at 16:29, Alex Bennée <[email protected]> wrote: > > Peter Maydell <[email protected]> writes: > > > The rST syntax for a table uses ASCII art to draw the cell > > boundaries; then inside each cell the text is treated as a body > > element, so it is rendered the same way as text at the top level of a > > document. > > > > The "field examples" table was assuming a "literal document" format > > for its cell bodies; this meant that the single line cells were being > > rendered in plain text, not a fixed width font, and the multi line > > cells were rendered as definition-lists because of their "second and > > subsequent lines are indented" layout. > > > > Fix this by consistently using inline-code markup for the left column > > and literal blocks for the right column. (We want to be consistent > > within each column because a literal block renders differently to > > inline-code, with a green background.) > > > > Signed-off-by: Peter Maydell <[email protected]> > > --- > > You can see the mis-rendered version at > > https://www.qemu.org/docs/master/devel/decodetree.html > > --- > > docs/devel/decodetree.rst | 44 ++++++++++++++++++++++++--------------- > > 1 file changed, 27 insertions(+), 17 deletions(-) > > > > diff --git a/docs/devel/decodetree.rst b/docs/devel/decodetree.rst > > index 98ad33a487..33cd6fe583 100644 > > --- a/docs/devel/decodetree.rst > > +++ b/docs/devel/decodetree.rst > > @@ -64,23 +64,33 @@ A field with no ``fields`` and no ``!function`` is in > > error. > > > > Field examples: > > > > -+---------------------------+---------------------------------------------+ > > -| Input | Generated code | > > -+===========================+=============================================+ > > -| %disp 0:s16 | sextract(i, 0, 16) | > > -+---------------------------+---------------------------------------------+ > > -| %imm9 16:6 10:3 | extract(i, 16, 6) << 3 | extract(i, 10, 3) | > > -+---------------------------+---------------------------------------------+ > > -| %disp12 0:s1 1:1 2:10 | sextract(i, 0, 1) << 11 | | > > -| | extract(i, 1, 1) << 10 | | > > -| | extract(i, 2, 10) | > > -+---------------------------+---------------------------------------------+ > > -| %shimm8 5:s8 13:1 | expand_shimm8(sextract(i, 5, 8) << 1 | | > > -| !function=expand_shimm8 | extract(i, 13, 1)) | > > -+---------------------------+---------------------------------------------+ > > -| %sz_imm 10:2 sz:3 | expand_sz_imm(extract(i, 10, 2) << 3 | | > > -| !function=expand_sz_imm | extract(a->sz, 0, 3)) | > > -+---------------------------+---------------------------------------------+ > > ++-----------------------------+----------------------------------------------+ > > +| Input | Generated code > > | > > ++=============================+==============================================+ > > +| ``%disp 0:s16`` | :: > > | > > +| | > > | > > +| | sextract(i, 0, 16) > > | > > ++-----------------------------+----------------------------------------------+ > > +| ``%imm9 16:6 10:3`` | :: > > | > > +| | > > | > > +| | extract(i, 16, 6) << 3 | extract(i, 10, > > 3) | > > ++-----------------------------+----------------------------------------------+ > > +| ``%disp12 0:s1 1:1 2:10`` | :: > > | > > +| | > > | > > +| | sextract(i, 0, 1) << 11 | > > | > > +| | extract(i, 1, 1) << 10 | > > | > > +| | extract(i, 2, 10) > > | > > ++-----------------------------+----------------------------------------------+ > > +| ``%shimm8 5:s8 13:1 | :: > > | > > +| !function=expand_shimm8`` | > > | > > +| | expand_shimm8(sextract(i, 5, 8) << 1 | > > | > > +| | extract(i, 13, 1)) > > | > > ++-----------------------------+----------------------------------------------+ > > +| ``%sz_imm 10:2 sz:3 | :: > > | > > +| !function=expand_sz_imm`` | > > | > > +| | expand_sz_imm(extract(i, 10, 2) << 3 | > > | > > +| | extract(a->sz, 0, 3)) > > | > > ++-----------------------------+----------------------------------------------+ > > Shouldn't we just use the proper markup > > .. list-table:: Field Examples > :widths: 30 70 > :header-rows: 1 > > * - Input > - Generated Code > * - %disp 0:s16 > - sextract(i, 0, 16) > ... > > ?
What "proper markup"? This is using the "grid tables" syntax from https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#tables You're suggesting "list table" syntax, which requires that the data can be represented by a uniform two level bullet list. I don't think either is more "proper" than the other. (Can you even put literal-block markup inside a bullet list item?) thanks -- PMM
