Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Date:   Tue, 23 Aug 2022 23:01:10 +0200
From:   Luca Ceresoli <luca.ceresoli@bootlin.com>
To:     Peter Rosin <peda@axentia.se>
Cc:     linux-doc@vger.kernel.org, linux-i2c@vger.kernel.org,
        Wolfram Sang <wsa@kernel.org>, linux-kernel@vger.kernel.org
Subject: Re: [PATCH v2 2/3] docs: i2c: i2c-topology: reorder sections more
 logically
Message-ID: <20220823230110.115a3fc5@booty>
In-Reply-To: <19a22449-c9fb-1eba-9a47-3e3d340a13a1@axentia.se>
References: <20220822091050.47099-1-luca.ceresoli@bootlin.com>
        <20220822091050.47099-3-luca.ceresoli@bootlin.com>
        <19a22449-c9fb-1eba-9a47-3e3d340a13a1@axentia.se>
Organization: Bootlin
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Precedence: bulk

Hi Peter,

On Tue, 23 Aug 2022 11:26:51 +0200
Peter Rosin <peda@axentia.se> wrote:

> 2022-08-22 at 11:10, luca.ceresoli@bootlin.com wrote:
> > From: Luca Ceresoli <luca.ceresoli@bootlin.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.

> > +Parent-locked Caveats
> > +~~~~~~~~~~~~~~~~~~~~~
> > +
> > +When using a parent-locked mux, be aware of the following restrictions:
> > +
> > +* If you build a topology with a parent-locked mux being the child
> > +  of another mux, this might break a possible assumption from the
> > +  child mux that the root adapter is unused between its select op
> > +  and the actual transfer (e.g. if the child mux is auto-closing
> > +  and the parent mux issues I2C transfers as part of its select).
> > +  This is especially the case if the parent mux is mux-locked, but
> > +  it may also happen if the parent mux is parent-locked.
> > +
> > +* If select/deselect calls out to other subsystems such as gpio,
> > +  pinctrl, regmap or iio, it is essential that any I2C transfers
> > +  caused by these subsystems are unlocked. This can be convoluted to
> > +  accomplish, maybe even impossible if an acceptably clean solution
> > +  is sought.
> > +
> > +
> >    
> 
> Three empty lines is excessive and inconsistent with the other two
> ===-headers.

Indeed! Fix ready for v3, waiting on the above proposal.

-- 
Luca Ceresoli, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com