linux-kernel - Re: [PATCH v2 2/3] docs: i2c: i2c-topology: reorder sections more logically

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] [day] [month] [year] [list]

Message-ID: <102125ad-fbec-7f23-bb17-b73ff49fe57b@axentia.se>
Date:   Wed, 24 Aug 2022 09:25:39 +0200
From:   Peter Rosin <peda@...ntia.se>
To:     Luca Ceresoli <luca.ceresoli@...tlin.com>
Cc:     linux-doc@...r.kernel.org, linux-i2c@...r.kernel.org,
        Wolfram Sang <wsa@...nel.org>, linux-kernel@...r.kernel.org
Subject: Re: [PATCH v2 2/3] docs: i2c: i2c-topology: reorder sections more
 logically

2022-08-23 at 23:01, Luca Ceresoli wrote:
> Hi Peter,
> 
> On Tue, 23 Aug 2022 11:26:51 +0200
> Peter Rosin <peda@...ntia.se> wrote:
> 
>> 2022-08-22 at 11:10, luca.ceresoli@...tlin.com wrote:
>>> From: Luca Ceresoli <luca.ceresoli@...tlin.com>
>>>
>>> The sequence of sections is a bit confusing here:
>>>
>>>  * we list the mux locking scheme for existing drivers before introducing
>>>    what mux locking schemes are
>>>  * we list the caveats for each locking scheme (which are tricky) before
>>>    the example of the simple use case
>>>
>>> Restructure it entirely with the following logic:
>>>
>>>  * Intro ("I2C muxes and complex topologies")
>>>  * Locking
>>>    - mux-locked
>>>      - example
>>>      - caveats
>>>    - parent-locked
>>>      - example
>>>      - caveats
>>>  * Complex examples
>>>  * Mux type of existing device drivers
>>>
>>> While there, also apply some other improvements:
>>>
>>>  * convert the caveat list from a table (with only one column carrying
>>>    content) to a bullet list.  
>>
>> I want to be able to refer to a specific caveat if/when someone has
>> questions, so I prefer to have the caveats "named". Not that this is
>> very frequent, but if we do remove the tags now I'm sure I'm going
>> to need them a few minutes later...
> 
> Now I realize the reason for those labels. Thank you for taking time to
> explain!
> 
> What about this one:
> 
>   [ML1]
>     If you build a topology with ...
> 
> It's a definition list, and the [ML1] gets rendered in bold.
> 
> The advantage is the text is still rendered as a regular paragraph,
> with the same font etc, except the left margin is increased.

Sounds very good to me, go ahead! And feel free to add my ack right
away with those changes...

Cheers,
Peter