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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <20201231154519.25425c3b@lwn.net>
Date:   Thu, 31 Dec 2020 15:45:19 -0700
From:   Jonathan Corbet <corbet@....net>
To:     "Nícolas F. R. A. Prado" <nfraprado@...tonmail.com>
Cc:     Steven Rostedt <rostedt@...dmis.org>,
        Mathieu Desnoyers <mathieu.desnoyers@...icios.com>,
        Lai Jiangshan <jiangshanlai@...il.com>,
        Joel Fernandes <joel@...lfernandes.org>,
        Takashi Iwai <tiwai@...e.com>,
        Jaroslav Kysela <perex@...ex.cz>,
        Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
        Stephen Boyd <swboyd@...omium.org>, rcu@...r.kernel.org,
        alsa-devel@...a-project.org, linux-doc@...r.kernel.org,
        linux-kernel@...r.kernel.org, lkcamp@...ts.libreplanetbr.org,
        andrealmeid@...labora.com
Subject: Re: [PATCH v2] docs: Fix reST markup when linking to sections

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