Re: Potential translation of LKMM docs into ReST

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

Em Sun, 30 Mar 2025 12:09:22 -0400
Alan Stern <stern@rowland.harvard.edu> escreveu:

> On Sun, Mar 30, 2025 at 01:07:23PM +0200, Ignacio Encinas Rubio wrote:
> > Hello!
> > 
> > There is interest [1] to get the memory model documentation into the 
> > built docs. Akira pointed out that this was discussed in the past [2].
> > 
> > A couple of years have gone by, so I was wondering whether the decision
> > to keep plain text documentation still applies. 
> > 
> > There is an "easy" way [3] to get the plain text documentation into the
> > built docs, but I would be happy to work in a conversion into ReST if
> > that's what you want :)
> > 
> > Ccing people involved in [2]
> > 
> > Thanks!
> > 
> > [1] https://lore.kernel.org/all/87o6y5lvvg.fsf@trenco.lwn.net/
> > [2] https://lore.kernel.org/lkml/20190901133530.GL4125@linux.ibm.com/
> > [3] https://lore.kernel.org/all/20220927160559.97154-7-corbet@lwn.net/  
> 
> I have no great interest in seeing the memory model documentation 
> translated into ReST, but you're welcome to try it and see how it comes 
> out if you want.  Some of the files are likely to be easier to convert 
> than others.
> 
> The only restriction I will insist on is that if the resulting ReST 
> source files end up being unreadable because of all the markup they 
> contain then we must keep the original plain text files too.

I did some attempts to convert some of them to ReST. Some files
could be a little be tricky if we want them to be converted, but
it is possible to go to a minimal set of changes. For instance:

	Documentation/memory-barriers.txt

There is an outdated conversion of it could be found at:
	https://lkml.org/lkml/2017/5/18/1267

If you take a look on it, most of the changes are minimal. On a
quick look on my previous patch, what we have is:

1) the most relevant change: example blocks need to use "::", like:

    -in 24 different combinations:
    +in 24 different combinations::
 
 	STORE A=3,	STORE B=4,	y=LOAD A->3,	x=LOAD B->4
 	STORE A=3,	STORE B=4,	x=LOAD B->4,	y=LOAD A->3

2) This won't work:

	By: foo
	    bar

   As it will produce a warning and place everything on a single line.
   The smallest change would be to add a blank line after :, e.g.:

	By:
	    foo
	    bar

3) This is not valid list on ReST:

	 (*) element
	 (*) element

   On ReST, unumerated lists use either:

	- element
	- element

   or:

	* element
	* element 

   We may also use, instead, a numerated list with:
 
	(#) element
	(#) element

  On such case, Sphinx will automatically numerate the list
  This is what I proposed back them to make changes minimal,
  as i wouldn't need to adjust indentation.

4) Tables in ReST require an extra line before/after it:

	+	===============	=======================	===========================
	 	TYPE		MANDATORY		SMP CONDITIONAL
	 	===============	=======================	===========================
	 	GENERAL		mb()			smp_mb()
	 	WRITE		wmb()			smp_wmb()
	 	READ		rmb()			smp_rmb()
	 	DATA DEPENDENCY	read_barrier_depends()	smp_read_barrier_depends()
	+	===============	=======================	===========================

5) Footnotes on ReST require a different notation. Either:

	[1]_

   or:

	[#]_

   and, at the place they're used:


	.. [1] foo

   or

	.. [#] foo

 
6) Chapter numeration markups need to start from column 1. On files with
   sub-chapters, some changes to use the same markup might me needed (this is
   not the case of memory-barriers).

The remaining changes I did back then on such patch were cosmetic to make it
look more similar to other parts of Documentation, like using "Titles Case"
for chapters and converting CONTENTS to a comment for them to not appear at
the docs output (as Sphinx already generates a contents index).

Regards,
Mauro