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

[Peter Rosin]

2022-08-23 at 23:01, Luca Ceresoli wrote:
> Hi Peter,
> 
> On Tue, 23 Aug 2022 11:26:51 +0200
> Peter Rosin <peda@xxxxxxxxxx> wrote:
> 
>> 2022-08-22 at 11:10, luca.ceresoli@xxxxxxxxxxx wrote:
>>> From: Luca Ceresoli <luca.ceresoli@xxxxxxxxxxx>
>>>
>>> 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