Em Wed, 14 Oct 2020 23:14:00 +0900
Akira Yokosawa [off-list ref] escreveu:

On Wed, 14 Oct 2020 09:56:03 +0200, Mauro Carvalho Chehab wrote:

quoted

Em Tue, 13 Oct 2020 18:58:40 -0700
"Paul E. McKenney" [off-list ref] escreveu:
  

quoted

On Tue, Oct 13, 2020 at 12:38:36PM -0400, Alan Stern wrote:  

quoted

On Tue, Oct 13, 2020 at 09:33:54AM -0700, Paul E. McKenney wrote:    

quoted

On Tue, Oct 13, 2020 at 02:14:29PM +0200, Mauro Carvalho Chehab wrote:    

quoted

- 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