[PATCH] Documentation: RCU: whatisRCU: Fix formatting for section 2

Convert RCU API method text to sub-headings and
add hyperlink and superscript to 2 literary notes
under rcu_dereference() section

Signed-off-by: Amol Grover <redacted>
---
 Documentation/RCU/whatisRCU.rst | 34 +++++++++++++++++++++++++++------
 1 file changed, 28 insertions(+), 6 deletions(-)

diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst
index ae40c8bcc56c..3cf6e17d0065 100644
--- a/Documentation/RCU/whatisRCU.rst
+++ b/Documentation/RCU/whatisRCU.rst

@@ -150,6 +150,7 @@ later.  See the kernel docbook documentation for more info, or look directly
 at the function header comments.
 
 rcu_read_lock()
+^^^^^^^^^^^^^^^
 
 	void rcu_read_lock(void);
 

@@ -164,6 +165,7 @@ rcu_read_lock()
 	longer-term references to data structures.
 
 rcu_read_unlock()
+^^^^^^^^^^^^^^^^^
 
 	void rcu_read_unlock(void);
 

@@ -172,6 +174,7 @@ rcu_read_unlock()
 	read-side critical sections may be nested and/or overlapping.
 
 synchronize_rcu()
+^^^^^^^^^^^^^^^^^
 
 	void synchronize_rcu(void);
 

@@ -225,6 +228,7 @@ synchronize_rcu()
 	checklist.txt for some approaches to limiting the update rate.
 
 rcu_assign_pointer()
+^^^^^^^^^^^^^^^^^^^^
 
 	void rcu_assign_pointer(p, typeof(p) v);
 

@@ -245,6 +249,7 @@ rcu_assign_pointer()
 	the _rcu list-manipulation primitives such as list_add_rcu().
 
 rcu_dereference()
+^^^^^^^^^^^^^^^^^
 
 	typeof(p) rcu_dereference(p);
 

@@ -279,8 +284,10 @@ rcu_dereference()
 	if an update happened while in the critical section, and incur
 	unnecessary overhead on Alpha CPUs.
 
+.. _back_to_1:
+
 	Note that the value returned by rcu_dereference() is valid
-	only within the enclosing RCU read-side critical section [1].
+	only within the enclosing RCU read-side critical section |cs_1|.
 	For example, the following is -not- legal::
 
 		rcu_read_lock();

@@ -298,15 +305,27 @@ rcu_dereference()
 	it was acquired is just as illegal as doing so with normal
 	locking.
 
+.. _back_to_2:
+
 	As with rcu_assign_pointer(), an important function of
 	rcu_dereference() is to document which pointers are protected by
 	RCU, in particular, flagging a pointer that is subject to changing
 	at any time, including immediately after the rcu_dereference().
 	And, again like rcu_assign_pointer(), rcu_dereference() is
 	typically used indirectly, via the _rcu list-manipulation
-	primitives, such as list_for_each_entry_rcu() [2].
+	primitives, such as list_for_each_entry_rcu() |entry_2|.
+
+.. |cs_1| raw:: html
+
+	<a href="#cs"><sup>[1]</sup></a>
+
+.. |entry_2| raw:: html
 
-	[1] The variant rcu_dereference_protected() can be used outside
+	<a href="#entry"><sup>[2]</sup></a>
+
+.. _cs:
+
+	\ :sup:`[1]`\  The variant rcu_dereference_protected() can be used outside
 	of an RCU read-side critical section as long as the usage is
 	protected by locks acquired by the update-side code.  This variant
 	avoids the lockdep warning that would happen when using (for

@@ -317,15 +336,18 @@ rcu_dereference()
 	a lockdep expression to indicate which locks must be acquired
 	by the caller. If the indicated protection is not provided,
 	a lockdep splat is emitted.  See Documentation/RCU/Design/Requirements/Requirements.rst
-	and the API's code comments for more details and example usage.
+	and the API's code comments for more details and example usage. :ref:`back <back_to_1>`
+
+
+.. _entry:
 
-	[2] If the list_for_each_entry_rcu() instance might be used by
+	\ :sup:`[2]`\  If the list_for_each_entry_rcu() instance might be used by
 	update-side code as well as by RCU readers, then an additional
 	lockdep expression can be added to its list of arguments.
 	For example, given an additional "lock_is_held(&mylock)" argument,
 	the RCU lockdep code would complain only if this instance was
 	invoked outside of an RCU read-side critical section and without
-	the protection of mylock.
+	the protection of mylock. :ref:`back <back_to_2>`
 
 The following diagram shows how each API communicates among the
 reader, updater, and reclaimer.

-- 
2.20.1

On Mon, Nov 04, 2019 at 07:03:15PM +0530, Amol Grover wrote:

Convert RCU API method text to sub-headings and
add hyperlink and superscript to 2 literary notes
under rcu_dereference() section

Signed-off-by: Amol Grover <redacted>

Good stuff, but Phong Tran beat you to it.  If you are suggesting
changes to that patch, please send a reply to her email, which
may be found here:

https://lore.kernel.org/lkml/20191030233128.14997-1-tranmanphong@gmail.com/

There are several options for replying to this email listed at the
bottom of that web page.

							Thanx, Paul

On Mon, 04 Nov 2019, Amol Grover [off-list ref] wrote:

Please don't use raw. It's ugly and error prone. We have some raw output
for latex, but this would be the first for html.

What are you trying to achieve?

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Graphics Center

On Mon, Nov 04, 2019 at 07:03:28AM -0800, Paul E. McKenney wrote:

On Mon, Nov 04, 2019 at 07:03:15PM +0530, Amol Grover wrote:

quoted

Convert RCU API method text to sub-headings and
add hyperlink and superscript to 2 literary notes
under rcu_dereference() section

Signed-off-by: Amol Grover <redacted>

Good stuff, but Phong Tran beat you to it.  If you are suggesting
changes to that patch, please send a reply to her email, which
may be found here:

https://lore.kernel.org/lkml/20191030233128.14997-1-tranmanphong@gmail.com/

There are several options for replying to this email listed at the
bottom of that web page.

							Thanx, Paul

Thank you Paul! And that is correct, I was suggesting changes to
that patch. However, since that patch was already integrated into
the `dev` branch, I mistakenly believed this patch could be sent
independently. Sorry for the trouble, I'll re-send the patch the
correct way.

Thank you
Amol

quoted

---
 Documentation/RCU/whatisRCU.rst | 34 +++++++++++++++++++++++++++------
 1 file changed, 28 insertions(+), 6 deletions(-)

diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst
index ae40c8bcc56c..3cf6e17d0065 100644
--- a/Documentation/RCU/whatisRCU.rst
+++ b/Documentation/RCU/whatisRCU.rst

@@ -150,6 +150,7 @@ later.  See the kernel docbook documentation for more info, or look directly
 at the function header comments.
 
 rcu_read_lock()
+^^^^^^^^^^^^^^^
 
 	void rcu_read_lock(void);
 

@@ -164,6 +165,7 @@ rcu_read_lock()
 	longer-term references to data structures.
 
 rcu_read_unlock()
+^^^^^^^^^^^^^^^^^
 
 	void rcu_read_unlock(void);
 

@@ -172,6 +174,7 @@ rcu_read_unlock()
 	read-side critical sections may be nested and/or overlapping.
 
 synchronize_rcu()
+^^^^^^^^^^^^^^^^^
 
 	void synchronize_rcu(void);
 

@@ -225,6 +228,7 @@ synchronize_rcu()
 	checklist.txt for some approaches to limiting the update rate.
 
 rcu_assign_pointer()
+^^^^^^^^^^^^^^^^^^^^
 
 	void rcu_assign_pointer(p, typeof(p) v);
 

@@ -245,6 +249,7 @@ rcu_assign_pointer()
 	the _rcu list-manipulation primitives such as list_add_rcu().
 
 rcu_dereference()
+^^^^^^^^^^^^^^^^^
 
 	typeof(p) rcu_dereference(p);
 

@@ -279,8 +284,10 @@ rcu_dereference()
 	if an update happened while in the critical section, and incur
 	unnecessary overhead on Alpha CPUs.
 
+.. _back_to_1:
+
 	Note that the value returned by rcu_dereference() is valid
-	only within the enclosing RCU read-side critical section [1].
+	only within the enclosing RCU read-side critical section |cs_1|.
 	For example, the following is -not- legal::
 
 		rcu_read_lock();

@@ -298,15 +305,27 @@ rcu_dereference()
 	it was acquired is just as illegal as doing so with normal
 	locking.
 
+.. _back_to_2:
+
 	As with rcu_assign_pointer(), an important function of
 	rcu_dereference() is to document which pointers are protected by
 	RCU, in particular, flagging a pointer that is subject to changing
 	at any time, including immediately after the rcu_dereference().
 	And, again like rcu_assign_pointer(), rcu_dereference() is
 	typically used indirectly, via the _rcu list-manipulation
-	primitives, such as list_for_each_entry_rcu() [2].
+	primitives, such as list_for_each_entry_rcu() |entry_2|.
+
+.. |cs_1| raw:: html
+
+	<a href="#cs"><sup>[1]</sup></a>
+
+.. |entry_2| raw:: html
 
-	[1] The variant rcu_dereference_protected() can be used outside
+	<a href="#entry"><sup>[2]</sup></a>
+
+.. _cs:
+
+	\ :sup:`[1]`\  The variant rcu_dereference_protected() can be used outside
 	of an RCU read-side critical section as long as the usage is
 	protected by locks acquired by the update-side code.  This variant
 	avoids the lockdep warning that would happen when using (for

@@ -317,15 +336,18 @@ rcu_dereference()
 	a lockdep expression to indicate which locks must be acquired
 	by the caller. If the indicated protection is not provided,
 	a lockdep splat is emitted.  See Documentation/RCU/Design/Requirements/Requirements.rst
-	and the API's code comments for more details and example usage.
+	and the API's code comments for more details and example usage. :ref:`back <back_to_1>`
+
+
+.. _entry:
 
-	[2] If the list_for_each_entry_rcu() instance might be used by
+	\ :sup:`[2]`\  If the list_for_each_entry_rcu() instance might be used by
 	update-side code as well as by RCU readers, then an additional
 	lockdep expression can be added to its list of arguments.
 	For example, given an additional "lock_is_held(&mylock)" argument,
 	the RCU lockdep code would complain only if this instance was
 	invoked outside of an RCU read-side critical section and without
-	the protection of mylock.
+	the protection of mylock. :ref:`back <back_to_2>`
 
 The following diagram shows how each API communicates among the
 reader, updater, and reclaimer.

-- 
2.20.1

On Mon, Nov 04, 2019 at 05:15:34PM +0200, Jani Nikula wrote:

On Mon, 04 Nov 2019, Amol Grover [off-list ref] wrote:

quoted

Convert RCU API method text to sub-headings and
add hyperlink and superscript to 2 literary notes
under rcu_dereference() section

Signed-off-by: Amol Grover <redacted>
---
 Documentation/RCU/whatisRCU.rst | 34 +++++++++++++++++++++++++++------
 1 file changed, 28 insertions(+), 6 deletions(-)

diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst
index ae40c8bcc56c..3cf6e17d0065 100644
--- a/Documentation/RCU/whatisRCU.rst
+++ b/Documentation/RCU/whatisRCU.rst

@@ -150,6 +150,7 @@ later.  See the kernel docbook documentation for more info, or look directly
 at the function header comments.
 
 rcu_read_lock()
+^^^^^^^^^^^^^^^
 
 	void rcu_read_lock(void);
 

@@ -164,6 +165,7 @@ rcu_read_lock()
 	longer-term references to data structures.
 
 rcu_read_unlock()
+^^^^^^^^^^^^^^^^^
 
 	void rcu_read_unlock(void);
 

@@ -172,6 +174,7 @@ rcu_read_unlock()
 	read-side critical sections may be nested and/or overlapping.
 
 synchronize_rcu()
+^^^^^^^^^^^^^^^^^
 
 	void synchronize_rcu(void);
 

@@ -225,6 +228,7 @@ synchronize_rcu()
 	checklist.txt for some approaches to limiting the update rate.
 
 rcu_assign_pointer()
+^^^^^^^^^^^^^^^^^^^^
 
 	void rcu_assign_pointer(p, typeof(p) v);
 

@@ -245,6 +249,7 @@ rcu_assign_pointer()
 	the _rcu list-manipulation primitives such as list_add_rcu().
 
 rcu_dereference()
+^^^^^^^^^^^^^^^^^
 
 	typeof(p) rcu_dereference(p);
 

@@ -279,8 +284,10 @@ rcu_dereference()
 	if an update happened while in the critical section, and incur
 	unnecessary overhead on Alpha CPUs.
 
+.. _back_to_1:
+
 	Note that the value returned by rcu_dereference() is valid
-	only within the enclosing RCU read-side critical section [1].
+	only within the enclosing RCU read-side critical section |cs_1|.
 	For example, the following is -not- legal::
 
 		rcu_read_lock();

@@ -298,15 +305,27 @@ rcu_dereference()
 	it was acquired is just as illegal as doing so with normal
 	locking.
 
+.. _back_to_2:
+
 	As with rcu_assign_pointer(), an important function of
 	rcu_dereference() is to document which pointers are protected by
 	RCU, in particular, flagging a pointer that is subject to changing
 	at any time, including immediately after the rcu_dereference().
 	And, again like rcu_assign_pointer(), rcu_dereference() is
 	typically used indirectly, via the _rcu list-manipulation
-	primitives, such as list_for_each_entry_rcu() [2].
+	primitives, such as list_for_each_entry_rcu() |entry_2|.
+
+.. |cs_1| raw:: html

Please don't use raw. It's ugly and error prone. We have some raw output
for latex, but this would be the first for html.

What are you trying to achieve?

Hi Jani,
While going through the documentation I encountered a few footnotes (numbers
[1] and [2]) which referenced the actual footnote somewhere below the text.
They were particularly not straight-forward to find hence I decided to
link them to the footnote text which could be done using inline markup.
Then I tried to make them more appealing by converting to super-scripts
(the way they look like in books and websites). However, nested inline 
markup is not yet possible in reST hence I went with the html way to 
achieve the same. Too much?

Thank you
Amol

BR,
Jani.

quoted

+
+	<a href="#cs"><sup>[1]</sup></a>
+
+.. |entry_2| raw:: html
 
-	[1] The variant rcu_dereference_protected() can be used outside
+	<a href="#entry"><sup>[2]</sup></a>
+
+.. _cs:
+
+	\ :sup:`[1]`\  The variant rcu_dereference_protected() can be used outside
 	of an RCU read-side critical section as long as the usage is
 	protected by locks acquired by the update-side code.  This variant
 	avoids the lockdep warning that would happen when using (for

@@ -317,15 +336,18 @@ rcu_dereference()
 	a lockdep expression to indicate which locks must be acquired
 	by the caller. If the indicated protection is not provided,
 	a lockdep splat is emitted.  See Documentation/RCU/Design/Requirements/Requirements.rst
-	and the API's code comments for more details and example usage.
+	and the API's code comments for more details and example usage. :ref:`back <back_to_1>`
+
+
+.. _entry:
 
-	[2] If the list_for_each_entry_rcu() instance might be used by
+	\ :sup:`[2]`\  If the list_for_each_entry_rcu() instance might be used by
 	update-side code as well as by RCU readers, then an additional
 	lockdep expression can be added to its list of arguments.
 	For example, given an additional "lock_is_held(&mylock)" argument,
 	the RCU lockdep code would complain only if this instance was
 	invoked outside of an RCU read-side critical section and without
-	the protection of mylock.
+	the protection of mylock. :ref:`back <back_to_2>`
 
 The following diagram shows how each API communicates among the
 reader, updater, and reclaimer.

-- 
Jani Nikula, Intel Open Source Graphics Center

On Mon, Nov 04, 2019 at 10:46:41PM +0530, Amol Grover wrote:

On Mon, Nov 04, 2019 at 07:03:28AM -0800, Paul E. McKenney wrote:

quoted

On Mon, Nov 04, 2019 at 07:03:15PM +0530, Amol Grover wrote:

quoted

Convert RCU API method text to sub-headings and
add hyperlink and superscript to 2 literary notes
under rcu_dereference() section

Signed-off-by: Amol Grover <redacted>

Good stuff, but Phong Tran beat you to it.  If you are suggesting
changes to that patch, please send a reply to her email, which
may be found here:

https://lore.kernel.org/lkml/20191030233128.14997-1-tranmanphong@gmail.com/

There are several options for replying to this email listed at the
bottom of that web page.

Thank you Paul! And that is correct, I was suggesting changes to
that patch. However, since that patch was already integrated into
the `dev` branch, I mistakenly believed this patch could be sent
independently. Sorry for the trouble, I'll re-send the patch the
correct way.

It is of course only polite to include the author of the previous patch
on CC, both using the "Cc: Phong Tran [off-list ref]" tag
following your "Signed-off" by.

							Thanx, Paul

Thank you
Amol

quoted

quoted

---
 Documentation/RCU/whatisRCU.rst | 34 +++++++++++++++++++++++++++------
 1 file changed, 28 insertions(+), 6 deletions(-)

diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst
index ae40c8bcc56c..3cf6e17d0065 100644
--- a/Documentation/RCU/whatisRCU.rst
+++ b/Documentation/RCU/whatisRCU.rst

@@ -150,6 +150,7 @@ later.  See the kernel docbook documentation for more info, or look directly
 at the function header comments.
 
 rcu_read_lock()
+^^^^^^^^^^^^^^^
 
 	void rcu_read_lock(void);
 

@@ -164,6 +165,7 @@ rcu_read_lock()
 	longer-term references to data structures.
 
 rcu_read_unlock()
+^^^^^^^^^^^^^^^^^
 
 	void rcu_read_unlock(void);
 

@@ -172,6 +174,7 @@ rcu_read_unlock()
 	read-side critical sections may be nested and/or overlapping.
 
 synchronize_rcu()
+^^^^^^^^^^^^^^^^^
 
 	void synchronize_rcu(void);
 

@@ -225,6 +228,7 @@ synchronize_rcu()
 	checklist.txt for some approaches to limiting the update rate.
 
 rcu_assign_pointer()
+^^^^^^^^^^^^^^^^^^^^
 
 	void rcu_assign_pointer(p, typeof(p) v);
 

@@ -245,6 +249,7 @@ rcu_assign_pointer()
 	the _rcu list-manipulation primitives such as list_add_rcu().
 
 rcu_dereference()
+^^^^^^^^^^^^^^^^^
 
 	typeof(p) rcu_dereference(p);
 

@@ -279,8 +284,10 @@ rcu_dereference()
 	if an update happened while in the critical section, and incur
 	unnecessary overhead on Alpha CPUs.
 
+.. _back_to_1:
+
 	Note that the value returned by rcu_dereference() is valid
-	only within the enclosing RCU read-side critical section [1].
+	only within the enclosing RCU read-side critical section |cs_1|.
 	For example, the following is -not- legal::
 
 		rcu_read_lock();

@@ -298,15 +305,27 @@ rcu_dereference()
 	it was acquired is just as illegal as doing so with normal
 	locking.
 
+.. _back_to_2:
+
 	As with rcu_assign_pointer(), an important function of
 	rcu_dereference() is to document which pointers are protected by
 	RCU, in particular, flagging a pointer that is subject to changing
 	at any time, including immediately after the rcu_dereference().
 	And, again like rcu_assign_pointer(), rcu_dereference() is
 	typically used indirectly, via the _rcu list-manipulation
-	primitives, such as list_for_each_entry_rcu() [2].
+	primitives, such as list_for_each_entry_rcu() |entry_2|.
+
+.. |cs_1| raw:: html
+
+	<a href="#cs"><sup>[1]</sup></a>
+
+.. |entry_2| raw:: html
 
-	[1] The variant rcu_dereference_protected() can be used outside
+	<a href="#entry"><sup>[2]</sup></a>
+
+.. _cs:
+
+	\ :sup:`[1]`\  The variant rcu_dereference_protected() can be used outside
 	of an RCU read-side critical section as long as the usage is
 	protected by locks acquired by the update-side code.  This variant
 	avoids the lockdep warning that would happen when using (for

@@ -317,15 +336,18 @@ rcu_dereference()
 	a lockdep expression to indicate which locks must be acquired
 	by the caller. If the indicated protection is not provided,
 	a lockdep splat is emitted.  See Documentation/RCU/Design/Requirements/Requirements.rst
-	and the API's code comments for more details and example usage.
+	and the API's code comments for more details and example usage. :ref:`back <back_to_1>`
+
+
+.. _entry:
 
-	[2] If the list_for_each_entry_rcu() instance might be used by
+	\ :sup:`[2]`\  If the list_for_each_entry_rcu() instance might be used by
 	update-side code as well as by RCU readers, then an additional
 	lockdep expression can be added to its list of arguments.
 	For example, given an additional "lock_is_held(&mylock)" argument,
 	the RCU lockdep code would complain only if this instance was
 	invoked outside of an RCU read-side critical section and without
-	the protection of mylock.
+	the protection of mylock. :ref:`back <back_to_2>`
 
 The following diagram shows how each API communicates among the
 reader, updater, and reclaimer.

-- 
2.20.1

On Mon, 04 Nov 2019, Amol Grover [off-list ref] wrote:

On Mon, Nov 04, 2019 at 05:15:34PM +0200, Jani Nikula wrote:

quoted

On Mon, 04 Nov 2019, Amol Grover [off-list ref] wrote:

quoted

Convert RCU API method text to sub-headings and
add hyperlink and superscript to 2 literary notes
under rcu_dereference() section

Signed-off-by: Amol Grover <redacted>
---
 Documentation/RCU/whatisRCU.rst | 34 +++++++++++++++++++++++++++------
 1 file changed, 28 insertions(+), 6 deletions(-)

diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst
index ae40c8bcc56c..3cf6e17d0065 100644
--- a/Documentation/RCU/whatisRCU.rst
+++ b/Documentation/RCU/whatisRCU.rst

@@ -150,6 +150,7 @@ later.  See the kernel docbook documentation for more info, or look directly
 at the function header comments.
 
 rcu_read_lock()
+^^^^^^^^^^^^^^^
 
 	void rcu_read_lock(void);
 

@@ -164,6 +165,7 @@ rcu_read_lock()
 	longer-term references to data structures.
 
 rcu_read_unlock()
+^^^^^^^^^^^^^^^^^
 
 	void rcu_read_unlock(void);
 

@@ -172,6 +174,7 @@ rcu_read_unlock()
 	read-side critical sections may be nested and/or overlapping.
 
 synchronize_rcu()
+^^^^^^^^^^^^^^^^^
 
 	void synchronize_rcu(void);
 

@@ -225,6 +228,7 @@ synchronize_rcu()
 	checklist.txt for some approaches to limiting the update rate.
 
 rcu_assign_pointer()
+^^^^^^^^^^^^^^^^^^^^
 
 	void rcu_assign_pointer(p, typeof(p) v);
 

@@ -245,6 +249,7 @@ rcu_assign_pointer()
 	the _rcu list-manipulation primitives such as list_add_rcu().
 
 rcu_dereference()
+^^^^^^^^^^^^^^^^^
 
 	typeof(p) rcu_dereference(p);
 

@@ -279,8 +284,10 @@ rcu_dereference()
 	if an update happened while in the critical section, and incur
 	unnecessary overhead on Alpha CPUs.
 
+.. _back_to_1:
+
 	Note that the value returned by rcu_dereference() is valid
-	only within the enclosing RCU read-side critical section [1].
+	only within the enclosing RCU read-side critical section |cs_1|.
 	For example, the following is -not- legal::
 
 		rcu_read_lock();

@@ -298,15 +305,27 @@ rcu_dereference()
 	it was acquired is just as illegal as doing so with normal
 	locking.
 
+.. _back_to_2:
+
 	As with rcu_assign_pointer(), an important function of
 	rcu_dereference() is to document which pointers are protected by
 	RCU, in particular, flagging a pointer that is subject to changing
 	at any time, including immediately after the rcu_dereference().
 	And, again like rcu_assign_pointer(), rcu_dereference() is
 	typically used indirectly, via the _rcu list-manipulation
-	primitives, such as list_for_each_entry_rcu() [2].
+	primitives, such as list_for_each_entry_rcu() |entry_2|.
+
+.. |cs_1| raw:: html

Please don't use raw. It's ugly and error prone. We have some raw output
for latex, but this would be the first for html.

What are you trying to achieve?

Hi Jani,
While going through the documentation I encountered a few footnotes (numbers
[1] and [2]) which referenced the actual footnote somewhere below the text.
They were particularly not straight-forward to find hence I decided to
link them to the footnote text which could be done using inline markup.
Then I tried to make them more appealing by converting to super-scripts
(the way they look like in books and websites). However, nested inline 
markup is not yet possible in reST hence I went with the html way to 
achieve the same. Too much?

I suggest you use rst footnote markup. It's less of an eye sore in the
rst source, but provides you with the links in the generated output. And
typically would be superscript. In particular "autonumber labels" might
fit the bill. [1][2]

BR,
Jani.


[1] http://docutils.sourceforge.net/docs/user/rst/quickref.html#footnotes
[2] http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#footnotes

Thank you
Amol

quoted

BR,
Jani.

quoted

+
+	<a href="#cs"><sup>[1]</sup></a>
+
+.. |entry_2| raw:: html
 
-	[1] The variant rcu_dereference_protected() can be used outside
+	<a href="#entry"><sup>[2]</sup></a>
+
+.. _cs:
+
+	\ :sup:`[1]`\  The variant rcu_dereference_protected() can be used outside
 	of an RCU read-side critical section as long as the usage is
 	protected by locks acquired by the update-side code.  This variant
 	avoids the lockdep warning that would happen when using (for

@@ -317,15 +336,18 @@ rcu_dereference()
 	a lockdep expression to indicate which locks must be acquired
 	by the caller. If the indicated protection is not provided,
 	a lockdep splat is emitted.  See Documentation/RCU/Design/Requirements/Requirements.rst
-	and the API's code comments for more details and example usage.
+	and the API's code comments for more details and example usage. :ref:`back <back_to_1>`
+
+
+.. _entry:
 
-	[2] If the list_for_each_entry_rcu() instance might be used by
+	\ :sup:`[2]`\  If the list_for_each_entry_rcu() instance might be used by
 	update-side code as well as by RCU readers, then an additional
 	lockdep expression can be added to its list of arguments.
 	For example, given an additional "lock_is_held(&mylock)" argument,
 	the RCU lockdep code would complain only if this instance was
 	invoked outside of an RCU read-side critical section and without
-	the protection of mylock.
+	the protection of mylock. :ref:`back <back_to_2>`
 
 The following diagram shows how each API communicates among the
 reader, updater, and reclaimer.

-- 
Jani Nikula, Intel Open Source Graphics Center

-- 
Jani Nikula, Intel Open Source Graphics Center

On Tue, Nov 05, 2019 at 08:08:50AM +0200, Jani Nikula wrote:

On Mon, 04 Nov 2019, Amol Grover [off-list ref] wrote:

quoted

On Mon, Nov 04, 2019 at 05:15:34PM +0200, Jani Nikula wrote:

quoted

On Mon, 04 Nov 2019, Amol Grover [off-list ref] wrote:

quoted

Convert RCU API method text to sub-headings and
add hyperlink and superscript to 2 literary notes
under rcu_dereference() section

Signed-off-by: Amol Grover <redacted>
---
 Documentation/RCU/whatisRCU.rst | 34 +++++++++++++++++++++++++++------
 1 file changed, 28 insertions(+), 6 deletions(-)

diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst
index ae40c8bcc56c..3cf6e17d0065 100644
--- a/Documentation/RCU/whatisRCU.rst
+++ b/Documentation/RCU/whatisRCU.rst

@@ -150,6 +150,7 @@ later.  See the kernel docbook documentation for more info, or look directly
 at the function header comments.
 
 rcu_read_lock()
+^^^^^^^^^^^^^^^
 
 	void rcu_read_lock(void);
 

@@ -164,6 +165,7 @@ rcu_read_lock()
 	longer-term references to data structures.
 
 rcu_read_unlock()
+^^^^^^^^^^^^^^^^^
 
 	void rcu_read_unlock(void);
 

@@ -172,6 +174,7 @@ rcu_read_unlock()
 	read-side critical sections may be nested and/or overlapping.
 
 synchronize_rcu()
+^^^^^^^^^^^^^^^^^
 
 	void synchronize_rcu(void);
 

@@ -225,6 +228,7 @@ synchronize_rcu()
 	checklist.txt for some approaches to limiting the update rate.
 
 rcu_assign_pointer()
+^^^^^^^^^^^^^^^^^^^^
 
 	void rcu_assign_pointer(p, typeof(p) v);
 

@@ -245,6 +249,7 @@ rcu_assign_pointer()
 	the _rcu list-manipulation primitives such as list_add_rcu().
 
 rcu_dereference()
+^^^^^^^^^^^^^^^^^
 
 	typeof(p) rcu_dereference(p);
 

@@ -279,8 +284,10 @@ rcu_dereference()
 	if an update happened while in the critical section, and incur
 	unnecessary overhead on Alpha CPUs.
 
+.. _back_to_1:
+
 	Note that the value returned by rcu_dereference() is valid
-	only within the enclosing RCU read-side critical section [1].
+	only within the enclosing RCU read-side critical section |cs_1|.
 	For example, the following is -not- legal::
 
 		rcu_read_lock();

@@ -298,15 +305,27 @@ rcu_dereference()
 	it was acquired is just as illegal as doing so with normal
 	locking.
 
+.. _back_to_2:
+
 	As with rcu_assign_pointer(), an important function of
 	rcu_dereference() is to document which pointers are protected by
 	RCU, in particular, flagging a pointer that is subject to changing
 	at any time, including immediately after the rcu_dereference().
 	And, again like rcu_assign_pointer(), rcu_dereference() is
 	typically used indirectly, via the _rcu list-manipulation
-	primitives, such as list_for_each_entry_rcu() [2].
+	primitives, such as list_for_each_entry_rcu() |entry_2|.
+
+.. |cs_1| raw:: html

Please don't use raw. It's ugly and error prone. We have some raw output
for latex, but this would be the first for html.

What are you trying to achieve?

Hi Jani,
While going through the documentation I encountered a few footnotes (numbers
[1] and [2]) which referenced the actual footnote somewhere below the text.
They were particularly not straight-forward to find hence I decided to
link them to the footnote text which could be done using inline markup.
Then I tried to make them more appealing by converting to super-scripts
(the way they look like in books and websites). However, nested inline 
markup is not yet possible in reST hence I went with the html way to 
achieve the same. Too much?

I suggest you use rst footnote markup. It's less of an eye sore in the
rst source, but provides you with the links in the generated output. And
typically would be superscript. In particular "autonumber labels" might
fit the bill. [1][2]

BR,
Jani.


[1] http://docutils.sourceforge.net/docs/user/rst/quickref.html#footnotes
[2] http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#footnotes

quoted

Thank you
Amol

quoted

BR,
Jani.

quoted

+
+	<a href="#cs"><sup>[1]</sup></a>
+
+.. |entry_2| raw:: html
 
-	[1] The variant rcu_dereference_protected() can be used outside
+	<a href="#entry"><sup>[2]</sup></a>
+
+.. _cs:
+
+	\ :sup:`[1]`\  The variant rcu_dereference_protected() can be used outside
 	of an RCU read-side critical section as long as the usage is
 	protected by locks acquired by the update-side code.  This variant
 	avoids the lockdep warning that would happen when using (for

@@ -317,15 +336,18 @@ rcu_dereference()
 	a lockdep expression to indicate which locks must be acquired
 	by the caller. If the indicated protection is not provided,
 	a lockdep splat is emitted.  See Documentation/RCU/Design/Requirements/Requirements.rst
-	and the API's code comments for more details and example usage.
+	and the API's code comments for more details and example usage. :ref:`back <back_to_1>`
+
+
+.. _entry:
 
-	[2] If the list_for_each_entry_rcu() instance might be used by
+	\ :sup:`[2]`\  If the list_for_each_entry_rcu() instance might be used by
 	update-side code as well as by RCU readers, then an additional
 	lockdep expression can be added to its list of arguments.
 	For example, given an additional "lock_is_held(&mylock)" argument,
 	the RCU lockdep code would complain only if this instance was
 	invoked outside of an RCU read-side critical section and without
-	the protection of mylock.
+	the protection of mylock. :ref:`back <back_to_2>`
 
 The following diagram shows how each API communicates among the
 reader, updater, and reclaimer.

-- 
Jani Nikula, Intel Open Source Graphics Center

-- 
Jani Nikula, Intel Open Source Graphics Center

Thank you for the feedback Paul and Jani! Sent the updated
patch at
https://lore.kernel.org/lkml/20191105073340.GA3682@workstation-kernel-dev/
with the requested changes.

Thank you
Amol

Hi Amol,

On 11/4/19 12:45 PM, Paul E. McKenney wrote:

On Mon, Nov 04, 2019 at 10:46:41PM +0530, Amol Grover wrote:

quoted

On Mon, Nov 04, 2019 at 07:03:28AM -0800, Paul E. McKenney wrote:

quoted

On Mon, Nov 04, 2019 at 07:03:15PM +0530, Amol Grover wrote:

quoted

Convert RCU API method text to sub-headings and
add hyperlink and superscript to 2 literary notes
under rcu_dereference() section

Signed-off-by: Amol Grover <redacted>

Good stuff, but Phong Tran beat you to it.  If you are suggesting
changes to that patch, please send a reply to her email, which
may be found here:

Please do a review and send comments and suggestions in an email
instead of a patch.

quoted

quoted

https://lore.kernel.org/lkml/20191030233128.14997-1-tranmanphong@gmail.com/

There are several options for replying to this email listed at the
bottom of that web page.

Thank you Paul! And that is correct, I was suggesting changes to
that patch. However, since that patch was already integrated into
the `dev` branch, I mistakenly believed this patch could be sent
independently. Sorry for the trouble, I'll re-send the patch the
correct way.

Please drop your patch and do a review for the patch as suggested by
Paul. This should have been a review and not a patch on top.

thanks,
-- Shuah

On Tue, Nov 05, 2019 at 07:52:59AM -0700, Shuah Khan wrote:

Hi Amol,

On 11/4/19 12:45 PM, Paul E. McKenney wrote:

quoted

On Mon, Nov 04, 2019 at 10:46:41PM +0530, Amol Grover wrote:

quoted

On Mon, Nov 04, 2019 at 07:03:28AM -0800, Paul E. McKenney wrote:

quoted

On Mon, Nov 04, 2019 at 07:03:15PM +0530, Amol Grover wrote:

quoted

Convert RCU API method text to sub-headings and
add hyperlink and superscript to 2 literary notes
under rcu_dereference() section

Signed-off-by: Amol Grover <redacted>

Good stuff, but Phong Tran beat you to it.  If you are suggesting
changes to that patch, please send a reply to her email, which
may be found here:

Please do a review and send comments and suggestions in an email
instead of a patch.

Hi Shuah,

Sure thing! I'll do a review and send in the suggestions.

quoted

quoted

quoted

https://lore.kernel.org/lkml/20191030233128.14997-1-tranmanphong@gmail.com/

There are several options for replying to this email listed at the
bottom of that web page.

Thank you Paul! And that is correct, I was suggesting changes to
that patch. However, since that patch was already integrated into
the `dev` branch, I mistakenly believed this patch could be sent
independently. Sorry for the trouble, I'll re-send the patch the
correct way.

Please drop your patch and do a review for the patch as suggested by
Paul. This should have been a review and not a patch on top.

Noted. Will definitely keep this in mind the next time.

Thank you
Amol

thanks,
-- Shuah