forked from torvalds/linux
-
Notifications
You must be signed in to change notification settings - Fork 17
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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 <Section Name_>`__ 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: ccc9971 ("docs: rcu: convert some articles from html to ReST") Fixes: c8cce10 ("docs: Fix the reference labels in Locking.rst") Fixes: e548cde ("docs-rst: convert kernel-locking to ReST") Fixes: 7ddedeb ("ALSA: doc: ReSTize writing-an-alsa-driver document") Signed-off-by: Nícolas F. R. A. Prado <[email protected]> Reviewed-by: Takashi Iwai <[email protected]> Reviewed-by: Mauro Carvalho Chehab <[email protected]> Link: https://lore.kernel.org/r/[email protected] Signed-off-by: Jonathan Corbet <[email protected]>
- Loading branch information
Nícolas F. R. A. Prado
authored and
Jonathan Corbet
committed
Dec 31, 2020
1 parent
5c8fe58
commit 4f8af07
Showing
4 changed files
with
26 additions
and
26 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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 critical sections. In | | ||
| RCU `(SRCU) <Sleepable RCU_>`__ read-side critical sections. In | | ||
| addition, the -rt patchset turns spinlocks into a sleeping locks so | | ||
| that the corresponding critical sections can be preempted, which also | | ||
| means that these sleeplockified spinlocks (but not other sleeping | | ||
|
@@ -1186,7 +1186,7 @@ non-preemptible (``CONFIG_PREEMPT=n``) kernels, and thus `tiny | |
RCU <https://lkml.kernel.org/g/[email protected]>`__ | ||
was born. Josh Triplett has since taken over the small-memory banner | ||
with his `Linux kernel tinification <https://tiny.wiki.kernel.org/>`__ | ||
project, which resulted in `SRCU <#Sleepable%20RCU>`__ becoming optional | ||
project, which resulted in `SRCU <Sleepable RCU_>`__ becoming optional | ||
for those kernels not needing it. | ||
|
||
The remaining performance requirements are, for the most part, | ||
|
@@ -1457,8 +1457,8 @@ will vary as the value of ``HZ`` varies, and can also be changed using | |
the relevant Kconfig options and kernel boot parameters. RCU currently | ||
does not do much sanity checking of these parameters, so please use | ||
caution when changing them. Note that these forward-progress measures | ||
are provided only for RCU, not for `SRCU <#Sleepable%20RCU>`__ or `Tasks | ||
RCU <#Tasks%20RCU>`__. | ||
are provided only for RCU, not for `SRCU <Sleepable RCU_>`__ or `Tasks | ||
RCU`_. | ||
|
||
RCU takes the following steps in ``call_rcu()`` to encourage timely | ||
invocation of callbacks when any given non-\ ``rcu_nocbs`` CPU has | ||
|
@@ -1477,8 +1477,8 @@ encouragement was provided: | |
|
||
Again, these are default values when running at ``HZ=1000``, and can be | ||
overridden. Again, these forward-progress measures are provided only for | ||
RCU, not for `SRCU <#Sleepable%20RCU>`__ or `Tasks | ||
RCU <#Tasks%20RCU>`__. Even for RCU, callback-invocation forward | ||
RCU, not for `SRCU <Sleepable RCU_>`__ or `Tasks | ||
RCU`_. Even for RCU, callback-invocation forward | ||
progress for ``rcu_nocbs`` CPUs is much less well-developed, in part | ||
because workloads benefiting from ``rcu_nocbs`` CPUs tend to invoke | ||
``call_rcu()`` relatively infrequently. If workloads emerge that need | ||
|
@@ -1920,7 +1920,7 @@ Hotplug CPU | |
|
||
The Linux kernel supports CPU hotplug, which means that CPUs can come | ||
and go. It is of course illegal to use any RCU API member from an | ||
offline CPU, with the exception of `SRCU <#Sleepable%20RCU>`__ read-side | ||
offline CPU, with the exception of `SRCU <Sleepable RCU_>`__ read-side | ||
critical sections. This requirement was present from day one in | ||
DYNIX/ptx, but on the other hand, the Linux kernel's CPU-hotplug | ||
implementation is “interesting.” | ||
|
@@ -2177,7 +2177,7 @@ handles these states differently: | |
However, RCU must be reliably informed as to whether any given CPU is | ||
currently in the idle loop, and, for ``NO_HZ_FULL``, also whether that | ||
CPU is executing in usermode, as discussed | ||
`earlier <#Energy%20Efficiency>`__. It also requires that the | ||
`earlier <Energy Efficiency_>`__. It also requires that the | ||
scheduling-clock interrupt be enabled when RCU needs it to be: | ||
|
||
#. If a CPU is either idle or executing in usermode, and RCU believes it | ||
|
@@ -2294,7 +2294,7 @@ Performance, Scalability, Response Time, and Reliability | |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
Expanding on the `earlier | ||
discussion <#Performance%20and%20Scalability>`__, RCU is used heavily by | ||
discussion <Performance and Scalability_>`__, RCU is used heavily by | ||
hot code paths in performance-critical portions of the Linux kernel's | ||
networking, security, virtualization, and scheduling code paths. RCU | ||
must therefore use efficient implementations, especially in its | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters