Am 06.09.21 um 16:17 schrieb Jonathan Corbet:

Markus Heiser [off-list ref] writes:

quoted

We prefer list tables ...

"""Their advantage is that they are easy to create or modify and that the
diff of a modification is much more meaningful, because it is limited to
the modified content."""

By example: We have some very large tables with tons of rows and cols.
If you need to extend one column just by one character you have to edit
the whole table and the diff is not readable.

It is not limited to big tables, e.g. if you patch a simple typo,
you might need touch content not related to your fix.

At the end it is a trade of, what weights more, readability of the
plain text or readability of the patch / most often I would vote
for the latter.

If the documentation is of any use of all there will be a lot more
people reading it than will be reading patches making tweaks to it.
Optimizing for patch readability seems like the wrong focus to me.

The ext4 folks can decide what they like best in this specific case.
But I think that the advice in favor of list tables is wrong in the
general case; they are completely unreadable in their source form, and
that goes against one of the key reasons we adopted RST in the first
place.

Somebody will surely try to add a list table to the wrong document
someday and I'll get to live through another one of those nifty
explosions - and I'll have neither reasons nor motivation to defend that
policy.

I do not see a problem changing the policy to use pre-formated tables.

@jon do you like to fix the "list tables" section of doc-guide/sphinx.rst

Thanks,

Markus