Re: [PATCH v2 02/24] tools: docs: memory-model: fix references for some files

From: Akira Yokosawa <akiyks@gmail.com>
To: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
	"Paul E. McKenney" <paulmck@kernel.org>
Cc: Alan Stern <stern@rowland.harvard.edu>,
	Linux Doc Mailing List <linux-doc@vger.kernel.org>,
	Jonathan Corbet <corbet@lwn.net>,
	Andrea Parri <parri.andrea@gmail.com>,
	Boqun Feng <boqun.feng@gmail.com>,
	Daniel Lustig <dlustig@nvidia.com>,
	David Howells <dhowells@redhat.com>,
	Jade Alglave <j.alglave@ucl.ac.uk>,
	Joel Fernandes <joel@joelfernandes.org>,
	Luc Maranget <luc.maranget@inria.fr>,
	Nicholas Piggin <npiggin@gmail.com>,
	Peter Zijlstra <peterz@infradead.org>,
	Will Deacon <will@kernel.org>,
	linux-arch@vger.kernel.org, linux-kernel@vger.kernel.org,
	Akira Yokosawa <akiyks@gmail.com>
Subject: Re: [PATCH v2 02/24] tools: docs: memory-model: fix references for some files
Date: Wed, 14 Oct 2020 23:14:00 +0900	[thread overview]
Message-ID: <aaeeba66-48be-0354-8f1c-261b361ae17f@gmail.com> (raw)
In-Reply-To: <20201014095603.0d899da7@coco.lan>

On Wed, 14 Oct 2020 09:56:03 +0200, Mauro Carvalho Chehab wrote:
> Em Tue, 13 Oct 2020 18:58:40 -0700
> "Paul E. McKenney" <paulmck@kernel.org> escreveu:
> 
>> On Tue, Oct 13, 2020 at 12:38:36PM -0400, Alan Stern wrote:
>>> On Tue, Oct 13, 2020 at 09:33:54AM -0700, Paul E. McKenney wrote:  
>>>> On Tue, Oct 13, 2020 at 02:14:29PM +0200, Mauro Carvalho Chehab wrote:  
>>>>> - The sysfs.txt file was converted to ReST and renamed;
>>>>> - The control-dependencies.txt is not at
>>>>>   Documentation/control-dependencies.txt. As it is at the
>>>>>   same dir as the README file, which mentions it, just
>>>>>   remove Documentation/.
>>>>>
>>>>> With that, ./scripts/documentation-file-ref-check script
>>>>> is now happy again for files under tools/.
>>>>>
>>>>> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>  
>>>>
>>>> Queued for review and testing, likely target v5.11.  
>>>
>>> Instead of changing the path in the README reference, shouldn't 
>>> tools/memory-model/control-dependencies.txt be moved to its proper 
>>> position in .../Documentation?  
>>
>> You are of course quite right.  My thought is to let Mauro go ahead,
>> given his short deadline.  We can then make this "git mv" change once
>> v5.10-rc1 comes out, given that it should have Mauro's patches.  I have
>> added a reminder to my calendar.
> 
> Sounds like a plan to me.
> 
> 
> If it helps on 5.11 plans, converting this file to ReST format is quite
> trivial: it just needs to use "::" for C/asm code literal blocks, and 
> to replace "(*) " by something that matches ReST syntax for lists,
> like "(#) " or just "* ":
> 
> 	https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bullet-lists
> 
> See enclosed.

I'm afraid conversion of LKMM documents to ReST is unlikely to happen
any time soon.
It should wait until such time comes when the auto markup tools become
clever enough and .rst files looks exactly the same as plain .txt files.

Am I asking too much? :-)

        Thanks, Akira

> 
> Thanks,
> Mauro
> 
> [PATCH] convert control-dependencies.rst to ReST
> 

[snip]