[PATCH] Documentation: kcsan: fix "Plain Accesses and Data Races" URL in kcsan.rst

[PATCH] Documentation: kcsan: fix "Plain Accesses and Data Races" URL in kcsan.rst

[Ignacio Encinas]

Make the URL point to the "Plain Accesses and Data Races" section again
and prevent it from becoming stale by adding a commit id to it.

Signed-off-by: Ignacio Encinas <ignacio@iencinas.com>
---
I noticed this while reviewing the documentation.

The "fix" isn't perfect as the link might become stale because it points
to a fixed commit. Alternatively, we could lose the line number
altogether.
---
 Documentation/dev-tools/kcsan.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/dev-tools/kcsan.rst b/Documentation/dev-tools/kcsan.rst
index d81c42d1063eab5db0cba1786de287406ca3ebe7..8575178aa87f1402d777af516f5c0e2fc8a3379d 100644
--- a/Documentation/dev-tools/kcsan.rst
+++ b/Documentation/dev-tools/kcsan.rst
@@ -203,7 +203,7 @@ they happen concurrently in different threads, and at least one of them is a
 least one is a write. For a more thorough discussion and definition, see `"Plain
 Accesses and Data Races" in the LKMM`_.
 
-.. _"Plain Accesses and Data Races" in the LKMM: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/memory-model/Documentation/explanation.txt#n1922
+.. _"Plain Accesses and Data Races" in the LKMM: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/memory-model/Documentation/explanation.txt?id=8f6629c004b193d23612641c3607e785819e97ab#n2164
 
 Relationship with the Linux-Kernel Memory Consistency Model (LKMM)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

---
base-commit: 19b100b0116d703b9529f7bbbf797428de51816a
change-id: 20250306-fix-plain-access-url-8ae841efa479

Best regards,
-- 
Ignacio Encinas <ignacio@iencinas.com>

Re: [PATCH] Documentation: kcsan: fix "Plain Accesses and Data Races" URL in kcsan.rst

[Jonathan Corbet]

Ignacio Encinas <ignacio@iencinas.com> writes:

> Make the URL point to the "Plain Accesses and Data Races" section again
> and prevent it from becoming stale by adding a commit id to it.
>
> Signed-off-by: Ignacio Encinas <ignacio@iencinas.com>
> ---
> I noticed this while reviewing the documentation.
>
> The "fix" isn't perfect as the link might become stale because it points
> to a fixed commit. Alternatively, we could lose the line number
> altogether.
> ---
>  Documentation/dev-tools/kcsan.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/dev-tools/kcsan.rst b/Documentation/dev-tools/kcsan.rst
> index d81c42d1063eab5db0cba1786de287406ca3ebe7..8575178aa87f1402d777af516f5c0e2fc8a3379d 100644
> --- a/Documentation/dev-tools/kcsan.rst
> +++ b/Documentation/dev-tools/kcsan.rst
> @@ -203,7 +203,7 @@ they happen concurrently in different threads, and at least one of them is a
>  least one is a write. For a more thorough discussion and definition, see `"Plain
>  Accesses and Data Races" in the LKMM`_.
>  
> -.. _"Plain Accesses and Data Races" in the LKMM: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/memory-model/Documentation/explanation.txt#n1922
> +.. _"Plain Accesses and Data Races" in the LKMM: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/memory-model/Documentation/explanation.txt?id=8f6629c004b193d23612641c3607e785819e97ab#n2164
>  

This seems like an improvement over what we have, so I've applied it.

It would be best, of course, to get the memory-model documentation
properly into our built docs...someday...

Thanks,

jon

Re: [PATCH] Documentation: kcsan: fix "Plain Accesses and Data Races" URL in kcsan.rst

[Ignacio Encinas Rubio]

On 12/3/25 23:36, Jonathan Corbet wrote:
> It would be best, of course, to get the memory-model documentation
> properly into our built docs...someday...

I hadn't thought about this. If this sentiment is shared by the LKMM
people I would be happy to work on this. Has this ever been
proposed/discussed before?

Re: [PATCH] Documentation: kcsan: fix "Plain Accesses and Data Races" URL in kcsan.rst

[Akira Yokosawa]

Hello,

Ignacio Encinas Rubio wrote:
> On 12/3/25 23:36, Jonathan Corbet wrote:
>> It would be best, of course, to get the memory-model documentation
>> properly into our built docs...someday...
> 
> I hadn't thought about this. If this sentiment is shared by the LKMM
> people I would be happy to work on this. Has this ever been
> proposed/discussed before?
>

This might be something Jon would like to keep secret, but ...

See the message and the thread it belongs at:

    https://lore.kernel.org/lkml/Pine.LNX.4.44L0.1907310947340.1497-100000@iolanthe.rowland.org/

It happened in 2019 responding to Mauro's attempt to conversion of
LKMM docs.

I haven't see any change in sentiment among LKMM maintainers since.

Your way forward would be to keep those .txt files *pure plain text"
and to convert them on-the-fly into reST.  Of course only if such an
effort sounds worthwhile to you.

Another approach might be to include those docs literally.
Similar approach has applied to

    Documentation/
	atomic_t.txt
	atomic_bitops.txt
        memory-barriers.txt

Regards,
Akira

Re: [PATCH] Documentation: kcsan: fix "Plain Accesses and Data Races" URL in kcsan.rst

[Ignacio Encinas Rubio]

On 15/3/25 3:41, Akira Yokosawa wrote:
> This might be something Jon would like to keep secret, but ...
> 
> See the message and the thread it belongs at:
> 
>     https://lore.kernel.org/lkml/Pine.LNX.4.44L0.1907310947340.1497-100000@iolanthe.rowland.org/
> 
> It happened in 2019 responding to Mauro's attempt to conversion of
> LKMM docs.
> 
> I haven't see any change in sentiment among LKMM maintainers since.

Thanks for the information!

> Your way forward would be to keep those .txt files *pure plain text"
> and to convert them on-the-fly into reST.  Of course only if such an
> effort sounds worthwhile to you.

With this you mean producing a .rst from the original .txt file using an 
script before building the documentation, right? I'm not sure how hard 
this is, but I can look into it.

> Another approach might be to include those docs literally.
> Similar approach has applied to
> 
>     Documentation/
> 	atomic_t.txt
> 	atomic_bitops.txt
>         memory-barriers.txt

Right, I got to [1]. 

It looks like there are several options here:

  A) Include the text files like in [1]
  B) Explore the "on-the-fly" translation
  C) Do A) and then B)

Does any of the above sound good, Jon?

Thank you both for your time

[1] https://lore.kernel.org/all/20220927160559.97154-7-corbet@lwn.net/

Re: [PATCH] Documentation: kcsan: fix "Plain Accesses and Data Races" URL in kcsan.rst

[Jonathan Corbet]

Ignacio Encinas Rubio <ignacio@iencinas.com> writes:

> On 15/3/25 3:41, Akira Yokosawa wrote:
>> This might be something Jon would like to keep secret, but ...
>> 
>> See the message and the thread it belongs at:
>> 
>>     https://lore.kernel.org/lkml/Pine.LNX.4.44L0.1907310947340.1497-100000@iolanthe.rowland.org/
>> 
>> It happened in 2019 responding to Mauro's attempt to conversion of
>> LKMM docs.
>> 
>> I haven't see any change in sentiment among LKMM maintainers since.
>
> Thanks for the information!

FWIW, I don't think it has really been discussed since.

>> Your way forward would be to keep those .txt files *pure plain text"
>> and to convert them on-the-fly into reST.  Of course only if such an
>> effort sounds worthwhile to you.
>
> With this you mean producing a .rst from the original .txt file using an 
> script before building the documentation, right? I'm not sure how hard 
> this is, but I can look into it.
>
>> Another approach might be to include those docs literally.
>> Similar approach has applied to
>> 
>>     Documentation/
>> 	atomic_t.txt
>> 	atomic_bitops.txt
>>         memory-barriers.txt
>
> Right, I got to [1]. 
>
> It looks like there are several options here:
>
>   A) Include the text files like in [1]
>   B) Explore the "on-the-fly" translation
>   C) Do A) and then B)
>
> Does any of the above sound good, Jon?

Using the wrapper technique will surely work and should be an
improvement over what we have now.  I don't hold out much hope for "on
the fly" mangling of the text - it sounds brittle and never quite good
enough, but I'm willing to be proved wrong on that front.

The original discussion from all those years ago centered around worries
about inserting lots of markup into the plain-text file.  But I'm not
convinced that anything requires all that markup; indeed, the proposed
conversion at the time didn't do that.  The question was quickly dropped
because we had so much to do back then...

I think there might be value in trying another minimal-markup
conversion; it would be *nicer* to use more fonts in the HTML version,
but not doing so seems better than not having an HTML version at all.
But, obviously, there are no guarantees that it will clear the bar.

Thanks,

jon