Re: [PATCH v2] docs: Fix reST markup when linking to sections

From: Mauro Carvalho Chehab
Date: Mon Dec 28 2020 - 18:12:27 EST


Em Mon, 28 Dec 2020 14:46:07 +0000
Nícolas F. R. A. Prado <nfraprado@xxxxxxxxxxxxxx> 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 <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: 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 <nfraprado@xxxxxxxxxxxxxx>
> Reviewed-by: Takashi Iwai <tiwai@xxxxxxx>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>

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 <Forcing Quiescent States_>`__.
>
> 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_>`__.
>
> 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 <Putting It All Together_>`__. |
> +-----------------------------------------------------------------------+
>
> 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 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/20090113221724.GA15307@xxxxxxxxxxxxxxxxxx>`__
> 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.”
> @@ -2147,7 +2147,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
> @@ -2264,7 +2264,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
> diff --git a/Documentation/kernel-hacking/locking.rst b/Documentation/kernel-hacking/locking.rst
> index 6ed806e6061b..c3448929a824 100644
> --- a/Documentation/kernel-hacking/locking.rst
> +++ b/Documentation/kernel-hacking/locking.rst
> @@ -118,11 +118,11 @@ spinlock, but you may block holding a mutex. If you can't lock a mutex,
> your task will suspend itself, and be woken up when the mutex is
> released. This means the CPU can do something else while you are
> waiting. There are many cases when you simply can't sleep (see
> -`What Functions Are Safe To Call From Interrupts? <#sleeping-things>`__),
> +`What Functions Are Safe To Call From Interrupts?`_),
> and so have to use a spinlock instead.
>
> Neither type of lock is recursive: see
> -`Deadlock: Simple and Advanced <#deadlock>`__.
> +`Deadlock: Simple and Advanced`_.
>
> Locks and Uniprocessor Kernels
> ------------------------------
> @@ -179,7 +179,7 @@ perfect world).
>
> Note that you can also use spin_lock_irq() or
> spin_lock_irqsave() here, which stop hardware interrupts
> -as well: see `Hard IRQ Context <#hard-irq-context>`__.
> +as well: see `Hard IRQ Context`_.
>
> This works perfectly for UP as well: the spin lock vanishes, and this
> macro simply becomes local_bh_disable()
> @@ -230,7 +230,7 @@ The Same Softirq
> ~~~~~~~~~~~~~~~~
>
> The same softirq can run on the other CPUs: you can use a per-CPU array
> -(see `Per-CPU Data <#per-cpu-data>`__) for better performance. If you're
> +(see `Per-CPU Data`_) for better performance. If you're
> going so far as to use a softirq, you probably care about scalable
> performance enough to justify the extra complexity.
>
> diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
> index 73bbd59afc33..e6365836fa8b 100644
> --- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
> +++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
> @@ -71,7 +71,7 @@ core/oss
> The codes for PCM and mixer OSS emulation modules are stored in this
> directory. The rawmidi OSS emulation is included in the ALSA rawmidi
> code since it's quite small. The sequencer code is stored in
> -``core/seq/oss`` directory (see `below <#core-seq-oss>`__).
> +``core/seq/oss`` directory (see `below <core/seq/oss_>`__).
>
> core/seq
> ~~~~~~~~
> @@ -382,7 +382,7 @@ where ``enable[dev]`` is the module option.
> Each time the ``probe`` callback is called, check the availability of
> the device. If not available, simply increment the device index and
> returns. dev will be incremented also later (`step 7
> -<#set-the-pci-driver-data-and-return-zero>`__).
> +<7) Set the PCI driver data and return zero._>`__).
>
> 2) Create a card instance
> ~~~~~~~~~~~~~~~~~~~~~~~~~
> @@ -450,10 +450,10 @@ field contains the information shown in ``/proc/asound/cards``.
> 5) Create other components, such as mixer, MIDI, etc.
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> -Here you define the basic components such as `PCM <#PCM-Interface>`__,
> -mixer (e.g. `AC97 <#API-for-AC97-Codec>`__), MIDI (e.g.
> -`MPU-401 <#MIDI-MPU401-UART-Interface>`__), and other interfaces.
> -Also, if you want a `proc file <#Proc-Interface>`__, define it here,
> +Here you define the basic components such as `PCM <PCM Interface_>`__,
> +mixer (e.g. `AC97 <API for AC97 Codec_>`__), MIDI (e.g.
> +`MPU-401 <MIDI (MPU401-UART) Interface_>`__), and other interfaces.
> +Also, if you want a `proc file <Proc Interface_>`__, define it here,
> too.
>
> 6) Register the card instance.
> @@ -941,7 +941,7 @@ The allocation of an interrupt source is done like this:
> chip->irq = pci->irq;
>
> where :c:func:`snd_mychip_interrupt()` is the interrupt handler
> -defined `later <#pcm-interface-interrupt-handler>`__. Note that
> +defined `later <PCM Interrupt Handler_>`__. Note that
> ``chip->irq`` should be defined only when :c:func:`request_irq()`
> succeeded.
>
> @@ -3104,7 +3104,7 @@ processing the output stream in the irq handler.
>
> If the MPU-401 interface shares its interrupt with the other logical
> devices on the card, set ``MPU401_INFO_IRQ_HOOK`` (see
> -`below <#MIDI-Interrupt-Handler>`__).
> +`below <MIDI Interrupt Handler_>`__).
>
> Usually, the port address corresponds to the command port and port + 1
> corresponds to the data port. If not, you may change the ``cport``



Thanks,
Mauro