On Mon, 24 Feb 2020 10:52:27 -0800
Matthew Wilcox [off-list ref] wrote:

On Mon, Feb 24, 2020 at 07:47:19PM +0100, Jonathan Neuschäfer wrote:

quoted

On Mon, Feb 24, 2020 at 11:08:15AM -0700, Jonathan Corbet wrote:  

quoted

On Sun, 23 Feb 2020 23:22:27 +0100
Jonathan Neuschäfer [off-list ref] wrote:
  

quoted

Without double-backticks, Sphinx wrongly turns "--version" into
"–version" with a Unicode EN DASH (U+2013), that is visually easy to
confuse with a single ASCII dash.

Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net>  

This certainly seems worth addressing.  But I would *really* rather find
a way to tell Sphinx not to do that rather than making all of these
tweaks - which we will certainly find ourselves having to do over and
over again.  I can try to look into that in a bit, but if somebody were
to beat me to it ... :)  

This seems to do the trick:

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 3c7bdf4cd31f..8f2a7ae95184 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py

@@ -587,6 +587,9 @@ pdf_documents = [
 kerneldoc_bin = '../scripts/kernel-doc'
 kerneldoc_srctree = '..'

+# Render -- as two dashes
+smartquotes = False  

I think what Jon was looking for was the ability to selectively turn
smartquotes off for a section and then reenable it?

No that's not what I was thinking, actually.  Unless somebody can come up
with a good reason to the contrary, just disabling that behavior globally
strikes me as the right thing to do.

Assuming there are no objections, it would be great to have this as a
patch with a proper changelog.  Said changelog should describe all of the
changes we'll see in the output with that option set, though, so there
are no surprises later.

Thanks,

jon