linux-ext4 - Re: [PATCH 1/2] ext4: docs: switch away from list-table

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <68ae637d-dc8d-cedc-b058-8f4ebb146137@darmarit.de>
Date:   Sat, 4 Sep 2021 09:45:17 +0200
From:   Markus Heiser <markus.heiser@...marit.de>
To:     Akira Yokosawa <akiyks@...il.com>, Jonathan Corbet <corbet@....net>
Cc:     jack@...e.cz, linux-doc@...r.kernel.org,
        linux-ext4@...r.kernel.org, tytso@....edu,
        Mauro Carvalho Chehab <mchehab@...nel.org>
Subject: Re: [PATCH 1/2] ext4: docs: switch away from list-table

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@...il.com> 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
>>