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

[Mauro Carvalho Chehab]

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