Re: [PATCH] Documentation/process/changes: Escape --options to fix Sphinx output

[Akira Yokosawa]

[Dropped most CCs]

Hi Jon,

On Thu, 20 Apr 2023 09:40:39 -0600, Jonathan Corbet wrote:
> Jonathan Corbet <corbet@xxxxxxx> writes:
> 
>> 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.
> 
> 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'll
> just drop the attached patch into docs-next.
> 
> Thanks for bringing this up!
> 
> jon
> 
> ------------8<-----------------
> From 995addeb4ab2a2c4beaf8b90a4dc8c1d64735d29 Mon Sep 17 00:00:00 2001
> From: Jonathan Corbet <corbet@xxxxxxx>
> Date: Thu, 20 Apr 2023 09:34:35 -0600
> Subject: [PATCH] docs: turn off "smart quotes" in the HTML build
> 
> We have long disabled the "html_use_smartypants" option to prevent Sphinx
> from mangling "--" sequences (among others).  Unfortunately, Sphinx changed
> 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 hope
> that the option name stays stable for a while.

Hi,
Whereas the summary reads "docs: turn off "smart quotes" in the HTML build",
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-dbd9960ba620@xxxxxxxxx/

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. 

        Thanks, Akira

> 
> Reported-by: Zipeng Zhang <zhangzipeng0@xxxxxxxxxxx>
> Link: https://lore.kernel.org/lkml/tencent_CB1A298D31FD221496FF657CD7EF406E6605@xxxxxx
> Signed-off-by: Jonathan Corbet <corbet@xxxxxxx>
> ---
>  Documentation/conf.py | 7 ++++---
>  1 file changed, 4 insertions(+), 3 deletions(-)
> 
> 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.css".
>  html_static_path = ['sphinx-static']
>  
> -# If true, SmartyPants will be used to convert quotes and dashes to
> -# typographically correct entities.
> -html_use_smartypants = False
> +# If true, Docutils "smart quotes will be used to convert quotes and dashes
> +# to typographically correct entities.  This will convert "--" to "—",
> +# which is not always what we want, so disable it.
> +smartquotes = False
>  
>  # Custom sidebar templates, maps document names to template names.
>  # Note that the RTD theme ignores this
> -- 
> 2.40.0