linux/Documentation/sound
Nícolas F. R. A. Prado 4f8af077a0 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: ccc9971e21 ("docs: rcu: convert some articles from html to ReST")
Fixes: c8cce10a62 ("docs: Fix the reference labels in Locking.rst")
Fixes: e548cdeffc ("docs-rst: convert kernel-locking to ReST")
Fixes: 7ddedebb03 ("ALSA: doc: ReSTize writing-an-alsa-driver document")
Signed-off-by: Nícolas F. R. A. Prado <nfraprado@protonmail.com>
Reviewed-by: Takashi Iwai <tiwai@suse.de>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/20201228144537.135353-1-nfraprado@protonmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-12-31 15:44:47 -07:00
..
cards Documentation: sound/cards: fix heading underline lengths for https: changes 2020-08-24 08:30:06 +02:00
designs docs: get rid of :c:type explicit declarations for structs 2020-10-15 07:49:40 +02:00
hd-audio ALSA: Replace HTTP links with HTTPS ones 2020-07-19 20:49:25 +02:00
kernel-api docs: Fix reST markup when linking to sections 2020-12-31 15:44:47 -07:00
soc ASoC: Replace HTTP links with HTTPS ones 2020-07-22 14:31:55 +01:00
alsa-configuration.rst ALSA: usb-audio: Add implicit_fb module option 2020-11-23 15:17:24 +01:00
index.rst docs: index.rst: don't use genindex for pdf output 2019-07-31 13:31:16 -06:00