Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Message-ID: <7e3b424d-2aba-3326-29c8-2ccdbfb12f70@gmail.com>
Date:   Sat, 22 Apr 2023 12:39:11 +0900
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101
 Thunderbird/102.10.0
To:     corbet@lwn.net
Cc:     linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        Akira Yokosawa <akiyks@gmail.com>
References: <87o7nitvd4.fsf@meer.lwn.net>
Subject: Re: [PATCH] Documentation/process/changes: Escape --options to fix
 Sphinx output
Content-Language: en-US
From:   Akira Yokosawa <akiyks@gmail.com>
In-Reply-To: <87o7nitvd4.fsf@meer.lwn.net>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
Precedence: bulk

[Dropped most CCs]

Hi Jon,

On Thu, 20 Apr 2023 09:40:39 -0600, Jonathan Corbet wrote:
> Jonathan Corbet <corbet@lwn.net> writes:
>=20
>> The right solution, if it is possible, is to convince Sphinx to stop
>> messing with "--" altogether.  Substituting em-dashes is of limited
>> cosmetic value and, I think, is something we could do without.
>=20
> Ah ... I get it now.  We *did* disable this once by disabling the
> "html_use_smartypants" option in conf.py.  The Sphinx folks changed the=

> name of that option in the 1.6.6 release, though, silently turning that=

> behavior back on.  It only took us five years to notice...  I think I'l=
l
> just drop the attached patch into docs-next.
>=20
> Thanks for bringing this up!
>=20
> jon
>=20
> ------------8<-----------------
> From 995addeb4ab2a2c4beaf8b90a4dc8c1d64735d29 Mon Sep 17 00:00:00 2001
> From: Jonathan Corbet <corbet@lwn.net>
> Date: Thu, 20 Apr 2023 09:34:35 -0600
> Subject: [PATCH] docs: turn off "smart quotes" in the HTML build
>=20
> We have long disabled the "html_use_smartypants" option to prevent Sphi=
nx
> from mangling "--" sequences (among others).  Unfortunately, Sphinx cha=
nged
> that option to "smartquotes" in the 1.6.6 release, and seemingly didn't=
 see
> fit to warn about the use of the obsolete option, resulting in the
> aforementioned mangling returning.  Disable this behavior again and hop=
e
> that the option name stays stable for a while.

Hi,
Whereas the summary reads "docs: turn off "smart quotes" in the HTML buil=
d",
the change is also effective in the LaTeX/PDF build.

BTW, Jon, don't you test build pdfdocs these days?

The fix to the pdfdocs build error from Tomi [1] is not yet picked up
either by Mauro or you ... :-/

[1] https://lore.kernel.org/linux-doc/29380b3e-1daa-3aef-1749-dbd9960ba62=
0@gmail.com/

I waited to see if there is anybody else who hits this build error.
It looks like I am alone!

If there is so few interest in pdfdocs, it might not be worth keeping
kernel documentation compatible with PDF build.=20

        Thanks, Akira

>=20
> Reported-by: Zipeng Zhang <zhangzipeng0@foxmail.com>
> Link: https://lore.kernel.org/lkml/tencent_CB1A298D31FD221496FF657CD7EF=
406E6605@qq.com
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
>  Documentation/conf.py | 7 ++++---
>  1 file changed, 4 insertions(+), 3 deletions(-)
>=20
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index db16814f182f..3d1f74f76e64 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -343,9 +343,10 @@ sys.stderr.write("Using %s theme\n" % html_theme)
>  # so a file named "default.css" will overwrite the builtin "default.cs=
s".
>  html_static_path =3D ['sphinx-static']
> =20
> -# If true, SmartyPants will be used to convert quotes and dashes to
> -# typographically correct entities.
> -html_use_smartypants =3D False
> +# If true, Docutils "smart quotes will be used to convert quotes and d=
ashes
> +# to typographically correct entities.  This will convert "--" to "=E2=
=80=94",
> +# which is not always what we want, so disable it.
> +smartquotes =3D False
> =20
>  # Custom sidebar templates, maps document names to template names.
>  # Note that the RTD theme ignores this
> --=20
> 2.40.0