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;
Message-ID: <206a95eb-5430-f9bf-15ad-4e644393255e@gmail.com>
Date:   Tue, 8 Nov 2022 09:29:01 +0700
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101
 Thunderbird/102.4.1
Subject: Re: [PATCH] Documentation: RCU: use code blocks with autogenerated
 line (was: Re: linux-next: build warning after merge of the rcu tree)
Content-Language: en-US
To:     Akira Yokosawa <akiyks@gmail.com>
Cc:     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,
        paulmck@kernel.org, quic_neeraju@quicinc.com, rcu@vger.kernel.org,
        rostedt@goodmis.org, sfr@canb.auug.org.au
References: <Y2jWAR1QESe3OrhH@debian.me>
 <af3ec8bf-310e-69ea-9d32-f7aec740b306@gmail.com>
From:   Bagas Sanjaya <bagasdotme@gmail.com>
In-Reply-To: <af3ec8bf-310e-69ea-9d32-f7aec740b306@gmail.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk

On 11/7/22 18:48, Akira Yokosawa wrote:
> 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.
> 

I think only rcubarrier.rst have explicit references to line numbers.

Also, besides manual line counting, readers seeing rst sources can deduce
where actually the lines are from explanation of the snippet. Of course
they can make htmldocs and seeing the output if they want.

> 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.
> 

There's also :emphasize-lines: option to highlight selected line numbers.

Thanks.

-- 
An old man doll... just what I always wanted! - Clara