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.
Or did the discussions take place after the list table support had been
added?
Thanks, Akira (a newcomer to kerneldoc)
>
> Thanks,
>
> jon
>
