[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
