* [PATCH] docs/devel/decodetree: Fix formatting in "field examples" table
@ 2026-03-09 15:26 Peter Maydell
2026-03-09 16:29 ` Alex Bennée
0 siblings, 1 reply; 5+ messages in thread
From: Peter Maydell @ 2026-03-09 15:26 UTC (permalink / raw)
To: qemu-devel; +Cc: Richard Henderson, Pierrick Bouvier
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.0
^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH] docs/devel/decodetree: Fix formatting in "field examples" table
2026-03-09 15:26 [PATCH] docs/devel/decodetree: Fix formatting in "field examples" table Peter Maydell
@ 2026-03-09 16:29 ` Alex Bennée
2026-03-09 16:45 ` Peter Maydell
0 siblings, 1 reply; 5+ messages in thread
From: Alex Bennée @ 2026-03-09 16:29 UTC (permalink / raw)
To: Peter Maydell; +Cc: qemu-devel, Richard Henderson, Pierrick Bouvier
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)
...
?
>
> Argument Sets
> =============
--
Alex Bennée
Virtualisation Tech Lead @ Linaro
^ permalink raw reply [flat|nested] 5+ messages in thread* Re: [PATCH] docs/devel/decodetree: Fix formatting in "field examples" table
2026-03-09 16:29 ` Alex Bennée
@ 2026-03-09 16:45 ` Peter Maydell
2026-04-30 13:10 ` Alex Bennée
0 siblings, 1 reply; 5+ messages in thread
From: Peter Maydell @ 2026-03-09 16:45 UTC (permalink / raw)
To: Alex Bennée; +Cc: qemu-devel, Richard Henderson, Pierrick Bouvier
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
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] docs/devel/decodetree: Fix formatting in "field examples" table
2026-03-09 16:45 ` Peter Maydell
@ 2026-04-30 13:10 ` Alex Bennée
2026-04-30 13:31 ` Peter Maydell
0 siblings, 1 reply; 5+ messages in thread
From: Alex Bennée @ 2026-04-30 13:10 UTC (permalink / raw)
To: Peter Maydell; +Cc: qemu-devel, Richard Henderson, Pierrick Bouvier
Peter Maydell <peter.maydell@linaro.org> writes:
> 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
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
--
Alex Bennée
Virtualisation Tech Lead @ Linaro
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] docs/devel/decodetree: Fix formatting in "field examples" table
2026-04-30 13:10 ` Alex Bennée
@ 2026-04-30 13:31 ` Peter Maydell
0 siblings, 0 replies; 5+ messages in thread
From: Peter Maydell @ 2026-04-30 13:31 UTC (permalink / raw)
To: Alex Bennée; +Cc: qemu-devel, Richard Henderson, Pierrick Bouvier
On Thu, 30 Apr 2026 at 14:10, Alex Bennée <alex.bennee@linaro.org> wrote:
>
> Peter Maydell <peter.maydell@linaro.org> writes:
>
> > 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.)
>
> Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Thanks; I'll take this patch via target-arm.next.
-- PMM
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2026-04-30 14:23 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-03-09 15:26 [PATCH] docs/devel/decodetree: Fix formatting in "field examples" table Peter Maydell
2026-03-09 16:29 ` Alex Bennée
2026-03-09 16:45 ` Peter Maydell
2026-04-30 13:10 ` Alex Bennée
2026-04-30 13:31 ` Peter Maydell
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.