* [PATCH -rcu] Documentation/RCU: Fix nested inline markup
@ 2021-05-21 2:16 Akira Yokosawa
2021-05-21 17:36 ` Paul E. McKenney
0 siblings, 1 reply; 2+ messages in thread
From: Akira Yokosawa @ 2021-05-21 2:16 UTC (permalink / raw)
To: Paul E. McKenney
Cc: Josh Triplett, Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan,
Joel Fernandes, Jonathan Corbet, rcu, linux-doc, linux-kernel,
Akira Yokosawa
To avoid the ``foo`` markup inside the `bar`__ hyperlink marker,
use the "replace" directive [1].
This should restore the intended appearance of the link.
Tested with sphinx versions 1.7.9 and 2.4.4.
[1]: https://docutils.sourceforge.io/docs/ref/rst/directives.html#replace
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
Hi Paul,
This fixes broken-looking cross reference in section
"Publish/Subscribe Guarantee" at:
https://www.kernel.org/doc/html/latest/RCU/Design/Requirements/Requirements.html#publish-subscribe-guarantee
To-be-replaced macro string can be much shorter.
I preserved the whole string considering the readability of .rst.
Thanks, Akira
--
Documentation/RCU/Design/Requirements/Requirements.rst | 8 +++++---
1 file changed, 5 insertions(+), 3 deletions(-)
diff --git a/Documentation/RCU/Design/Requirements/Requirements.rst b/Documentation/RCU/Design/Requirements/Requirements.rst
index 38a39476fc24..45278e2974c0 100644
--- a/Documentation/RCU/Design/Requirements/Requirements.rst
+++ b/Documentation/RCU/Design/Requirements/Requirements.rst
@@ -362,9 +362,8 @@ do_something_gp() uses rcu_dereference() to fetch from ``gp``:
12 }
The rcu_dereference() uses volatile casts and (for DEC Alpha) memory
-barriers in the Linux kernel. Should a `high-quality implementation of
-C11 ``memory_order_consume``
-[PDF] <http://www.rdrop.com/users/paulmck/RCU/consume.2015.07.13a.pdf>`__
+barriers in the Linux kernel. Should a |high-quality implementation of
+C11 memory_order_consume [PDF]|_
ever appear, then rcu_dereference() could be implemented as a
``memory_order_consume`` load. Regardless of the exact implementation, a
pointer fetched by rcu_dereference() may not be used outside of the
@@ -374,6 +373,9 @@ element has been passed from RCU to some other synchronization
mechanism, most commonly locking or `reference
counting <https://www.kernel.org/doc/Documentation/RCU/rcuref.txt>`__.
+.. |high-quality implementation of C11 memory_order_consume [PDF]| replace:: high-quality implementation of C11 ``memory_order_consume`` [PDF]
+.. _high-quality implementation of C11 memory_order_consume [PDF]: http://www.rdrop.com/users/paulmck/RCU/consume.2015.07.13a.pdf
+
In short, updaters use rcu_assign_pointer() and readers use
rcu_dereference(), and these two RCU API elements work together to
ensure that readers have a consistent view of newly added data elements.
--
2.17.1
^ permalink raw reply related [flat|nested] 2+ messages in thread
* Re: [PATCH -rcu] Documentation/RCU: Fix nested inline markup
2021-05-21 2:16 [PATCH -rcu] Documentation/RCU: Fix nested inline markup Akira Yokosawa
@ 2021-05-21 17:36 ` Paul E. McKenney
0 siblings, 0 replies; 2+ messages in thread
From: Paul E. McKenney @ 2021-05-21 17:36 UTC (permalink / raw)
To: Akira Yokosawa
Cc: Josh Triplett, Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan,
Joel Fernandes, Jonathan Corbet, rcu, linux-doc, linux-kernel
On Fri, May 21, 2021 at 11:16:04AM +0900, Akira Yokosawa wrote:
> To avoid the ``foo`` markup inside the `bar`__ hyperlink marker,
> use the "replace" directive [1].
>
> This should restore the intended appearance of the link.
>
> Tested with sphinx versions 1.7.9 and 2.4.4.
>
> [1]: https://docutils.sourceforge.io/docs/ref/rst/directives.html#replace
>
> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Queued, thank you! Or if this should instead go via the Documentation
tree:
Acked-by: Paul E. McKenney <paulmck@kernel.org>
> ---
> Hi Paul,
>
> This fixes broken-looking cross reference in section
> "Publish/Subscribe Guarantee" at:
>
> https://www.kernel.org/doc/html/latest/RCU/Design/Requirements/Requirements.html#publish-subscribe-guarantee
>
> To-be-replaced macro string can be much shorter.
> I preserved the whole string considering the readability of .rst.
And completely agreed on keeping the .rst readable.
Thanx, Paul
> Thanks, Akira
> --
> Documentation/RCU/Design/Requirements/Requirements.rst | 8 +++++---
> 1 file changed, 5 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/RCU/Design/Requirements/Requirements.rst b/Documentation/RCU/Design/Requirements/Requirements.rst
> index 38a39476fc24..45278e2974c0 100644
> --- a/Documentation/RCU/Design/Requirements/Requirements.rst
> +++ b/Documentation/RCU/Design/Requirements/Requirements.rst
> @@ -362,9 +362,8 @@ do_something_gp() uses rcu_dereference() to fetch from ``gp``:
> 12 }
>
> The rcu_dereference() uses volatile casts and (for DEC Alpha) memory
> -barriers in the Linux kernel. Should a `high-quality implementation of
> -C11 ``memory_order_consume``
> -[PDF] <http://www.rdrop.com/users/paulmck/RCU/consume.2015.07.13a.pdf>`__
> +barriers in the Linux kernel. Should a |high-quality implementation of
> +C11 memory_order_consume [PDF]|_
> ever appear, then rcu_dereference() could be implemented as a
> ``memory_order_consume`` load. Regardless of the exact implementation, a
> pointer fetched by rcu_dereference() may not be used outside of the
> @@ -374,6 +373,9 @@ element has been passed from RCU to some other synchronization
> mechanism, most commonly locking or `reference
> counting <https://www.kernel.org/doc/Documentation/RCU/rcuref.txt>`__.
>
> +.. |high-quality implementation of C11 memory_order_consume [PDF]| replace:: high-quality implementation of C11 ``memory_order_consume`` [PDF]
> +.. _high-quality implementation of C11 memory_order_consume [PDF]: http://www.rdrop.com/users/paulmck/RCU/consume.2015.07.13a.pdf
> +
> In short, updaters use rcu_assign_pointer() and readers use
> rcu_dereference(), and these two RCU API elements work together to
> ensure that readers have a consistent view of newly added data elements.
> --
> 2.17.1
>
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2021-05-21 17:36 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-05-21 2:16 [PATCH -rcu] Documentation/RCU: Fix nested inline markup Akira Yokosawa
2021-05-21 17:36 ` Paul E. McKenney
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.