Re: [PATCH v2] docs: Fix reST markup when linking to sections
On Mon, 28 Dec 2020 14:46:07 + Nícolas F. R. A. Prado wrote: > During the process of converting the documentation to reST, some links > were converted using the following wrong syntax (and sometimes using %20 > instead of spaces): > >`Display text <#section-name-in-html>`__ > > This syntax isn't valid according to the docutils' spec [1], but more > importantly, it is specific to HTML, since it uses '#' to link to an > HTML anchor. > > The right syntax would instead use a docutils hyperlink reference as the > embedded URI to point to the section [2], that is: > >`Display text `__ > > This syntax works in both HTML and PDF. > > The LaTeX toolchain doesn't mind the HTML anchor syntax when generating > the pdf documentation (make pdfdocs), that is, the build succeeds but > the links don't work, but that syntax causes errors when trying to build > using the not-yet-merged rst2pdf: > >ValueError: format not resolved, probably missing URL scheme or undefined > destination target for 'Forcing%20Quiescent%20States' > > So, use the correct syntax in order to have it work in all different > output formats. Applied, thanks. jon
Re: [PATCH v2] docs: Fix reST markup when linking to sections
Em Mon, 28 Dec 2020 14:46:07 +
Nícolas F. R. A. Prado escreveu:
> During the process of converting the documentation to reST, some links
> were converted using the following wrong syntax (and sometimes using %20
> instead of spaces):
>
>`Display text <#section-name-in-html>`__
>
> This syntax isn't valid according to the docutils' spec [1], but more
> importantly, it is specific to HTML, since it uses '#' to link to an
> HTML anchor.
>
> The right syntax would instead use a docutils hyperlink reference as the
> embedded URI to point to the section [2], that is:
>
>`Display text `__
>
> This syntax works in both HTML and PDF.
>
> The LaTeX toolchain doesn't mind the HTML anchor syntax when generating
> the pdf documentation (make pdfdocs), that is, the build succeeds but
> the links don't work, but that syntax causes errors when trying to build
> using the not-yet-merged rst2pdf:
>
>ValueError: format not resolved, probably missing URL scheme or undefined
> destination target for 'Forcing%20Quiescent%20States'
>
> So, use the correct syntax in order to have it work in all different
> output formats.
>
> [1]:
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#reference-names
> [2]:
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#embedded-uris-and-aliases
>
> Fixes: ccc9971e2147 ("docs: rcu: convert some articles from html to ReST")
> Fixes: c8cce10a62aa ("docs: Fix the reference labels in Locking.rst")
> Fixes: e548cdeffcd8 ("docs-rst: convert kernel-locking to ReST")
> Fixes: 7ddedebb03b7 ("ALSA: doc: ReSTize writing-an-alsa-driver document")
> Signed-off-by: Nícolas F. R. A. Prado
> Reviewed-by: Takashi Iwai
Reviewed-by: Mauro Carvalho Chehab
Regards,
Mauro
> ---
>
> Changes in v2:
> - Thanks to Mauro:
> - Simplify the syntax of some links by taking advantage of docutils'
> case-insensitivity when dealing with references.
>
> .../Tree-RCU-Memory-Ordering.rst | 8
> .../RCU/Design/Requirements/Requirements.rst | 20 +--
> Documentation/kernel-hacking/locking.rst | 8
> .../kernel-api/writing-an-alsa-driver.rst | 16 +++
> 4 files changed, 26 insertions(+), 26 deletions(-)
>
> diff --git
> a/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst
> b/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst
> index e44cfcb7adcc..e57927427786 100644
> --- a/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst
> +++ b/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst
> @@ -473,7 +473,7 @@ read-side critical sections that follow the idle period
> (the oval near
> the bottom of the diagram above).
>
> Plumbing this into the full grace-period execution is described
> -`below <#Forcing%20Quiescent%20States>`__.
> +`below `__.
>
> CPU-Hotplug Interface
> ^
> @@ -494,7 +494,7 @@ mask to detect CPUs having gone offline since the
> beginning of this
> grace period.
>
> Plumbing this into the full grace-period execution is described
> -`below <#Forcing%20Quiescent%20States>`__.
> +`below `__.
>
> Forcing Quiescent States
>
> @@ -532,7 +532,7 @@ from other CPUs.
> | RCU. But this diagram is complex enough as it is, so simplicity |
> | overrode accuracy. You can think of it as poetic license, or you can |
> | think of it as misdirection that is resolved in the |
> -| `stitched-together diagram <#Putting%20It%20All%20Together>`__. |
> +| `stitched-together diagram `__. |
> +---+
>
> Grace-Period Cleanup
> @@ -596,7 +596,7 @@ maintain ordering. For example, if the callback function
> wakes up a task
> that runs on some other CPU, proper ordering must in place in both the
> callback function and the task being awakened. To see why this is
> important, consider the top half of the `grace-period
> -cleanup <#Grace-Period%20Cleanup>`__ diagram. The callback might be
> +cleanup`_ diagram. The callback might be
> running on a CPU corresponding to the leftmost leaf ``rcu_node``
> structure, and awaken a task that is to run on a CPU corresponding to
> the rightmost leaf ``rcu_node`` structure, and the grace-period kernel
> diff --git a/Documentation/RCU/Design/Requirements/Requirements.rst
> b/Documentation/RCU/Design/Requirements/Requirements.rst
> index 1ae79a10a8de..ce1075f040be 100644
> --- a/Documentation/RCU/Design/Requirements/Requirements.rst
> +++ b/Documentation/RCU/Design/Requirements/Requirements.rst
> @@ -45,7 +45,7 @@ requirements:
> #. `Other RCU Flavors`_
> #. `Possible Future Changes`_
>
> -This is followed by a `summary <#Summary>`__, however, the answers to
> +This is followed by a summary_, however, the answers to
> each quick quiz immediately follows the quiz. Select the big white space
> with your
[PATCH v2] docs: Fix reST markup when linking to sections
During the process of converting the documentation to reST, some links
were converted using the following wrong syntax (and sometimes using %20
instead of spaces):
`Display text <#section-name-in-html>`__
This syntax isn't valid according to the docutils' spec [1], but more
importantly, it is specific to HTML, since it uses '#' to link to an
HTML anchor.
The right syntax would instead use a docutils hyperlink reference as the
embedded URI to point to the section [2], that is:
`Display text `__
This syntax works in both HTML and PDF.
The LaTeX toolchain doesn't mind the HTML anchor syntax when generating
the pdf documentation (make pdfdocs), that is, the build succeeds but
the links don't work, but that syntax causes errors when trying to build
using the not-yet-merged rst2pdf:
ValueError: format not resolved, probably missing URL scheme or undefined
destination target for 'Forcing%20Quiescent%20States'
So, use the correct syntax in order to have it work in all different
output formats.
[1]:
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#reference-names
[2]:
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#embedded-uris-and-aliases
Fixes: ccc9971e2147 ("docs: rcu: convert some articles from html to ReST")
Fixes: c8cce10a62aa ("docs: Fix the reference labels in Locking.rst")
Fixes: e548cdeffcd8 ("docs-rst: convert kernel-locking to ReST")
Fixes: 7ddedebb03b7 ("ALSA: doc: ReSTize writing-an-alsa-driver document")
Signed-off-by: Nícolas F. R. A. Prado
Reviewed-by: Takashi Iwai
---
Changes in v2:
- Thanks to Mauro:
- Simplify the syntax of some links by taking advantage of docutils'
case-insensitivity when dealing with references.
.../Tree-RCU-Memory-Ordering.rst | 8
.../RCU/Design/Requirements/Requirements.rst | 20 +--
Documentation/kernel-hacking/locking.rst | 8
.../kernel-api/writing-an-alsa-driver.rst | 16 +++
4 files changed, 26 insertions(+), 26 deletions(-)
diff --git
a/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst
b/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst
index e44cfcb7adcc..e57927427786 100644
--- a/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst
+++ b/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst
@@ -473,7 +473,7 @@ read-side critical sections that follow the idle period
(the oval near
the bottom of the diagram above).
Plumbing this into the full grace-period execution is described
-`below <#Forcing%20Quiescent%20States>`__.
+`below `__.
CPU-Hotplug Interface
^
@@ -494,7 +494,7 @@ mask to detect CPUs having gone offline since the beginning
of this
grace period.
Plumbing this into the full grace-period execution is described
-`below <#Forcing%20Quiescent%20States>`__.
+`below `__.
Forcing Quiescent States
@@ -532,7 +532,7 @@ from other CPUs.
| RCU. But this diagram is complex enough as it is, so simplicity |
| overrode accuracy. You can think of it as poetic license, or you can |
| think of it as misdirection that is resolved in the |
-| `stitched-together diagram <#Putting%20It%20All%20Together>`__. |
+| `stitched-together diagram `__. |
+---+
Grace-Period Cleanup
@@ -596,7 +596,7 @@ maintain ordering. For example, if the callback function
wakes up a task
that runs on some other CPU, proper ordering must in place in both the
callback function and the task being awakened. To see why this is
important, consider the top half of the `grace-period
-cleanup <#Grace-Period%20Cleanup>`__ diagram. The callback might be
+cleanup`_ diagram. The callback might be
running on a CPU corresponding to the leftmost leaf ``rcu_node``
structure, and awaken a task that is to run on a CPU corresponding to
the rightmost leaf ``rcu_node`` structure, and the grace-period kernel
diff --git a/Documentation/RCU/Design/Requirements/Requirements.rst
b/Documentation/RCU/Design/Requirements/Requirements.rst
index 1ae79a10a8de..ce1075f040be 100644
--- a/Documentation/RCU/Design/Requirements/Requirements.rst
+++ b/Documentation/RCU/Design/Requirements/Requirements.rst
@@ -45,7 +45,7 @@ requirements:
#. `Other RCU Flavors`_
#. `Possible Future Changes`_
-This is followed by a `summary <#Summary>`__, however, the answers to
+This is followed by a summary_, however, the answers to
each quick quiz immediately follows the quiz. Select the big white space
with your mouse to see the answer.
@@ -1096,7 +1096,7 @@ memory barriers.
| case, voluntary context switch) within an RCU read-side critical |
| section. However, sleeping locks may be used within userspace RCU |
| read-side critical sections, and also within Linux-kernel sleepable |
-| RCU `(SRCU) <#Sleepable%20RCU>`__ read-side
