Re: [PATCH] docs/devel/decodetree: Fix formatting in "field examples" table

["Alex Bennée" <alex.bennee@linaro.org>]

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