linux-kernel - Re: [PATCH] docs: process: changes.rst: Escape --version to fix Sphinx output

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] [thread-next>] [day] [month] [year] [list]

Message-ID: <20200224115851.6684d516@lwn.net>
Date:   Mon, 24 Feb 2020 11:58:51 -0700
From:   Jonathan Corbet <corbet@....net>
To:     Matthew Wilcox <willy@...radead.org>
Cc:     Jonathan Neuschäfer <j.neuschaefer@....net>,
        linux-doc@...r.kernel.org, Andi Kleen <ak@...ux.intel.com>,
        Thomas Gleixner <tglx@...utronix.de>,
        Randy Dunlap <rdunlap@...radead.org>,
        "Darrick J. Wong" <darrick.wong@...cle.com>,
        Arnd Bergmann <arnd@...db.de>,
        "Chang S. Bae" <chang.seok.bae@...el.com>,
        linux-kernel@...r.kernel.org
Subject: Re: [PATCH] docs: process: changes.rst: Escape --version to fix
 Sphinx output

On Mon, 24 Feb 2020 10:52:27 -0800
Matthew Wilcox <willy@...radead.org> wrote:

> On Mon, Feb 24, 2020 at 07:47:19PM +0100, Jonathan Neuschäfer wrote:
> > On Mon, Feb 24, 2020 at 11:08:15AM -0700, Jonathan Corbet wrote:  
> > > On Sun, 23 Feb 2020 23:22:27 +0100
> > > Jonathan Neuschäfer <j.neuschaefer@....net> wrote:
> > >   
> > > > 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@....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