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: <26188ff7-9a0c-d72c-b956-63d8f1c500ba@gmail.com>
Date:   Wed, 9 Nov 2022 15:28:54 +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, linux-kernel@vger.kernel.org,
        linux-next@vger.kernel.org, paulmck@kernel.org, rcu@vger.kernel.org
References: <Y2jWAR1QESe3OrhH@debian.me>
 <af3ec8bf-310e-69ea-9d32-f7aec740b306@gmail.com>
 <206a95eb-5430-f9bf-15ad-4e644393255e@gmail.com>
 <fd1903d4-a721-931e-c928-1818cd650490@gmail.com>
From:   Bagas Sanjaya <bagasdotme@gmail.com>
In-Reply-To: <fd1903d4-a721-931e-c928-1818cd650490@gmail.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk

On 11/8/22 21:53, Akira Yokosawa wrote:
>> I think only rcubarrier.rst have explicit references to line numbers.
> 
> Oh, I find such references in (not limited to):
> 
>   - Documentation/RCU/Design/Requirements/Requirements.rst
>   - Documentation/RCU/Design/Data-Structures/Data-Structures.rst
> 

Ah, I don't see these above!

> Remember there is a note in Documentation/doc-guide/sphinx.rst
> which reads:
> 
>   Please don't go overboard with reStructuredText markup. Keep it simple.
>   For the most part the documentation should be plain text with just enough
>   consistency in formatting that it can be converted to other formats.
> 
> My interpretation of above:
> 
>   .rst sources should be kept as close to plain-text which can be
>   easily understood in dumb terminals, as far as possible.
> 

Ah! I always forget that. I'm leaning towards *abusing* the markup,
though.

Thanks for the reminder.

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