Re: Potential translation of LKMM docs into ReST

Mauro Carvalho Chehab
2025-03-30T17:52:58Z

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