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

[Jonathan Corbet]

On Mon, 28 Dec 2020 14:46:07 +0000
Nícolas F. R. A. Prado <nfraprado at protonmail.com> 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 <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.

Applied, thanks.

jon