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

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Wed, 14 Oct 2020 23:14:00 +0900
Akira Yokosawa <akiyks@gmail.com> escreveu:

> 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

Yes :-)

	$ git log --author akiyks@gmail.com Documentation/sphinx
	$

The auto markup tools don't write themselves alone. Someone needs 
to write them and test if no regressions will happen with the existing
documents.

-

That's said, I suspect that one of the hardest things for something
like that to be possible is to be able to distinguish something
like:

	(some text)

From something like:

	/* some C code snippet or bash script, or other literal block */

So, at least "::" (or some other markup replacing it) is needed.

If you have some bright idea about how to implement it, feel free
to contribute with patches.

Thanks,
Mauro