Am 04.09.21 um 03:23 schrieb Akira Yokosawa:
On Fri, 03 Sep 2021 09:11:26 -0600, Jonathan Corbet wrote:
Akira Yokosawa <akiyks@xxxxxxxxx> writes:
[Adding Mauro]
On Thu, 2 Sep 2021 16:08:53 -0600, Jonathan Corbet wrote:
Commit 3a6541e97c03 (Add documentation about the orphan file feature) added
a new document on orphan files, which is great. But the use of
"list-table" results in documents that are absolutely unreadable in their
plain-text form. Switch this file to the regular RST table format instead;
the rendered (HTML) output is identical.
In the "list tables" section of doc-guide/sphinx.rst, the first paragraph
starts with the sentence:
We recommend the use of list table formats.
Yes, the disadvantage of list tables is mentioned later in the paragraph:
Compared to the ASCII-art they might not be as comfortable for readers
of the text files.
, but I still see list-table is meant as the preferred format.
Interesting...that is not at all my memory of the discussions we had at
that time. There was a lot of pushback against anything that makes the
RST files less readable - still is, if certain people join the
conversation. Tables were one of the early flash points.
Mauro, you added that text; do you remember things differently? Do you
feel we should retain that recommendation?
No, the text was first added by Markus Heiser [added to CC] in commit
0249a7644857 ("doc-rst: flat-table directive - initial implementation")
and have not updated ever since.
He might remember the circumstances, but 2016 was a long time ago,
I guess.
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.
-- Markus --
Or did the discussions take place after the list table support had been
added?
Thanks, Akira (a newcomer to kerneldoc)
Thanks,
jon
