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

[Jonathan Corbet]

On Mon, 24 Feb 2020 10:52:27 -0800
Matthew Wilcox <willy@xxxxxxxxxxxxx> 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@xxxxxxx> 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@xxxxxxx>  
> > > 
> > > 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