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:   Mon, 7 Nov 2022 09:50:20 -0800
From:   "Paul E. McKenney" <paulmck@kernel.org>
To:     Akira Yokosawa <akiyks@gmail.com>
Cc:     Bagas Sanjaya <bagasdotme@gmail.com>, corbet@lwn.net,
        frederic@kernel.org, jiangshanlai@gmail.com,
        joel@joelfernandes.org, josh@joshtriplett.org,
        linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        linux-next@vger.kernel.org, mathieu.desnoyers@efficios.com,
        quic_neeraju@quicinc.com, rcu@vger.kernel.org, rostedt@goodmis.org,
        sfr@canb.auug.org.au
Subject: Re: [PATCH] Documentation: RCU: use code blocks with autogenerated
 line (was: Re: linux-next: build warning after merge of the rcu tree)
Message-ID: <20221107175020.GK28461@paulmck-ThinkPad-P17-Gen-1>
Reply-To: paulmck@kernel.org
References: <Y2jWAR1QESe3OrhH@debian.me>
 <af3ec8bf-310e-69ea-9d32-f7aec740b306@gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <af3ec8bf-310e-69ea-9d32-f7aec740b306@gmail.com>
Precedence: bulk

On Mon, Nov 07, 2022 at 08:48:23PM +0900, Akira Yokosawa wrote:
> Hi Bagas,
> 
> On Mon, 7 Nov 2022 16:55:13 +0700, Bagas Sanjaya wrote:
> > On Sun, Nov 06, 2022 at 09:02:12PM -0800, Paul E. McKenney wrote:
> >> On Mon, Nov 07, 2022 at 02:26:41PM +1100, Stephen Rothwell wrote:
> >> > Hi all,
> >> > 
> >> > After merging the rcu tree, today's linux-next build (htmldocs)
> >> > produced this warning:
> >> > 
> >> > Documentation/RCU/rcubarrier.rst:205: WARNING: Literal block ends without a blank line; unexpected unindent.
> >> > 
> >> > Introduced by commit
> >> > 
> >> >   21c2e3909721 ("doc: Update rcubarrier.rst")
> >> 
> >> Huh.  I guess that numbered code samples are not supposed to have more
> >> than nine lines?  Ah well, easy to fix by going back to left-justified
> >> numbers.  I was wondering about that!
> >> 
> > 
> > I think the proper fix is just let Sphinx generates line number:
> 
> That might be true if all you care about were the generated documents,
> but we need to pay attention to readers of .rst files as plain-text.
> 
> There are a bunch of references to line numbers in RCU documents.
> If explicit line numbers are removed from snippets, such readers need
> to count the lines by themselves, which doesn't sound reasonable to me.
> 
> If you can put labels to referenced lines within code snippets, auto
> generation of line numbers might work, but as far as I know, Sphinx
> doesn't provide such a nice feature.
> 
> Of course, you can prove me wrong.

I will give Bagas a few days to prove Akira wrong.  ;-)

Either way, thank you both for looking into this!

							Thanx, Paul