docs/devel/decodetree.rst | 44 ++++++++++++++++++++++++--------------- 1 file changed, 27 insertions(+), 17 deletions(-)
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 <peter.maydell@linaro.org>
---
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)) |
++-----------------------------+----------------------------------------------+
Argument Sets
=============
--
2.43.0Peter Maydell <peter.maydell@linaro.org> 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 <peter.maydell@linaro.org>
> ---
> 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)
...
?
>
> Argument Sets
> =============
--
Alex Bennée
Virtualisation Tech Lead @ Linaro
On Mon, 9 Mar 2026 at 16:29, Alex Bennée <alex.bennee@linaro.org> wrote: > > Peter Maydell <peter.maydell@linaro.org> 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 <peter.maydell@linaro.org> > > --- > > 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
© 2016 - 2026 Red Hat, Inc.