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

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

[Jonathan Neuschäfer]

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>
---
 Documentation/process/changes.rst | 52 +++++++++++++++----------------
 1 file changed, 26 insertions(+), 26 deletions(-)

diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst
index e47863575917..0aa765736b73 100644
--- a/Documentation/process/changes.rst
+++ b/Documentation/process/changes.rst
@@ -29,32 +29,32 @@ you probably needn't concern yourself with pcmciautils.
 ====================== ===============  ========================================
         Program        Minimal version       Command to check the version
 ====================== ===============  ========================================
-GNU C                  4.6              gcc --version
-GNU make               3.81             make --version
-binutils               2.21             ld -v
-flex                   2.5.35           flex --version
-bison                  2.0              bison --version
-util-linux             2.10o            fdformat --version
-kmod                   13               depmod -V
-e2fsprogs              1.41.4           e2fsck -V
-jfsutils               1.1.3            fsck.jfs -V
-reiserfsprogs          3.6.3            reiserfsck -V
-xfsprogs               2.6.0            xfs_db -V
-squashfs-tools         4.0              mksquashfs -version
-btrfs-progs            0.18             btrfsck
-pcmciautils            004              pccardctl -V
-quota-tools            3.09             quota -V
-PPP                    2.4.0            pppd --version
-nfs-utils              1.0.5            showmount --version
-procps                 3.2.0            ps --version
-oprofile               0.9              oprofiled --version
-udev                   081              udevd --version
-grub                   0.93             grub --version || grub-install --version
-mcelog                 0.6              mcelog --version
-iptables               1.4.2            iptables -V
-openssl & libcrypto    1.0.0            openssl version
-bc                     1.06.95          bc --version
-Sphinx\ [#f1]_	       1.3		sphinx-build --version
+GNU C                  4.6              ``gcc --version``
+GNU make               3.81             ``make --version``
+binutils               2.21             ``ld -v``
+flex                   2.5.35           ``flex --version``
+bison                  2.0              ``bison --version``
+util-linux             2.10o            ``fdformat --version``
+kmod                   13               ``depmod -V``
+e2fsprogs              1.41.4           ``e2fsck -V``
+jfsutils               1.1.3            ``fsck.jfs -V``
+reiserfsprogs          3.6.3            ``reiserfsck -V``
+xfsprogs               2.6.0            ``xfs_db -V``
+squashfs-tools         4.0              ``mksquashfs -version``
+btrfs-progs            0.18             ``btrfsck``
+pcmciautils            004              ``pccardctl -V``
+quota-tools            3.09             ``quota -V``
+PPP                    2.4.0            ``pppd --version``
+nfs-utils              1.0.5            ``showmount --version``
+procps                 3.2.0            ``ps --version``
+oprofile               0.9              ``oprofiled --version``
+udev                   081              ``udevd --version``
+grub                   0.93             ``grub --version || grub-install --version``
+mcelog                 0.6              ``mcelog --version``
+iptables               1.4.2            ``iptables -V``
+openssl & libcrypto    1.0.0            ``openssl version``
+bc                     1.06.95          ``bc --version``
+Sphinx\ [#f1]_	       1.3		``sphinx-build --version``
 ====================== ===============  ========================================

 .. [#f1] Sphinx is needed only to build the Kernel documentation
--
2.20.1

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

[Jonathan Corbet]

On Sun, 23 Feb 2020 23:22:27 +0100
Jonathan Neuschäfer <j.neuschaefer@gmx.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@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 ... :)

Thanks,

jon

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

[Jonathan Neuschäfer]

[-- Attachment #1: Type: text/plain, Size: 1438 bytes --]

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@gmx.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@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
+
 # ------------------------------------------------------------------------------
 # Since loadConfig overwrites settings from the global namespace, it has to be
 # the last statement in the conf.py file

(Documentation at https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-smartquotes)


Jonathan Neuschäfer

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Matthew Wilcox]

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@gmx.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@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?

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@infradead.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@gmx.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@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

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

[Matthew Wilcox]

On Mon, Feb 24, 2020 at 11:58:51AM -0700, Jonathan Corbet wrote:
> On Mon, 24 Feb 2020 10:52:27 -0800
> Matthew Wilcox <willy@infradead.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@gmx.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@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.

Well, sometimes -- when the time is right -- I like to use en-dashes.
It's probably no great loss, though.

grep finds me these interesting examples:

Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst:Tree RCU's grace--period memory-ordering guarantees rely most heavily on
Documentation/accounting/psi.rst:scarcity aids users in sizing workloads to hardware--or provisioning
Documentation/admin-guide/acpi/cppc_sysfs.rst:  -r--r--r-- 1 root root 65536 Mar  5 19:38 feedback_ctrs
Documentation/admin-guide/mm/hugetlbpage.rst:task that modifies ``nr_hugepages``. The default for the allowed nodes--when the
Documentation/block/null_blk.rst:home_node=[0--nr_nodes]: Default: NUMA_NO_NODE
Documentation/admin-guide/svga.rst::Copyright: |copy| 1995--1999 Martin Mares, <mj@ucw.cz>
Documentation/media/uapi/v4l/pixfmt-srggb10-ipu3.rst:        G\ :sub:`0108high`\ (bits 1--0)

(in all, 368 lines, but they're not all in .rst files)

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

[Randy Dunlap]

On 2/24/20 11:12 AM, Matthew Wilcox wrote:
> On Mon, Feb 24, 2020 at 11:58:51AM -0700, Jonathan Corbet wrote:
>> On Mon, 24 Feb 2020 10:52:27 -0800
>> Matthew Wilcox <willy@infradead.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@gmx.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@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.
> 
> Well, sometimes -- when the time is right -- I like to use en-dashes.
> It's probably no great loss, though.
> 
> grep finds me these interesting examples:
> 
> Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst:Tree RCU's grace--period memory-ordering guarantees rely most heavily on
> Documentation/accounting/psi.rst:scarcity aids users in sizing workloads to hardware--or provisioning
> Documentation/admin-guide/acpi/cppc_sysfs.rst:  -r--r--r-- 1 root root 65536 Mar  5 19:38 feedback_ctrs
> Documentation/admin-guide/mm/hugetlbpage.rst:task that modifies ``nr_hugepages``. The default for the allowed nodes--when the
> Documentation/block/null_blk.rst:home_node=[0--nr_nodes]: Default: NUMA_NO_NODE
> Documentation/admin-guide/svga.rst::Copyright: |copy| 1995--1999 Martin Mares, <mj@ucw.cz>
> Documentation/media/uapi/v4l/pixfmt-srggb10-ipu3.rst:        G\ :sub:`0108high`\ (bits 1--0)
> 
> (in all, 368 lines, but they're not all in .rst files)
> 

Not trying to be contrary, but I would prefer to keep .rst files as much
ASCII as possible.

-- 
~Randy

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

[Matthew Wilcox]

On Mon, Feb 24, 2020 at 01:08:13PM -0800, Randy Dunlap wrote:
> On 2/24/20 11:12 AM, Matthew Wilcox wrote:
> > On Mon, Feb 24, 2020 at 11:58:51AM -0700, Jonathan Corbet wrote:
> >> On Mon, 24 Feb 2020 10:52:27 -0800
> >> Matthew Wilcox <willy@infradead.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@gmx.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@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.
> > 
> > Well, sometimes -- when the time is right -- I like to use en-dashes.
> > It's probably no great loss, though.
> > 
> > grep finds me these interesting examples:
> > 
> > Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst:Tree RCU's grace--period memory-ordering guarantees rely most heavily on
> > Documentation/accounting/psi.rst:scarcity aids users in sizing workloads to hardware--or provisioning
> > Documentation/admin-guide/acpi/cppc_sysfs.rst:  -r--r--r-- 1 root root 65536 Mar  5 19:38 feedback_ctrs
> > Documentation/admin-guide/mm/hugetlbpage.rst:task that modifies ``nr_hugepages``. The default for the allowed nodes--when the
> > Documentation/block/null_blk.rst:home_node=[0--nr_nodes]: Default: NUMA_NO_NODE
> > Documentation/admin-guide/svga.rst::Copyright: |copy| 1995--1999 Martin Mares, <mj@ucw.cz>
> > Documentation/media/uapi/v4l/pixfmt-srggb10-ipu3.rst:        G\ :sub:`0108high`\ (bits 1--0)
> > 
> > (in all, 368 lines, but they're not all in .rst files)
> > 
> 
> Not trying to be contrary, but I would prefer to keep .rst files as much
> ASCII as possible.

I don't think anybody is arguing otherwise.  The question is whether
minusminus should be left as a pair of minus signs or whether it should
be converted into an en-dash.

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

[Jani Nikula]

On Mon, 24 Feb 2020, Matthew Wilcox <willy@infradead.org> wrote:
> On Mon, Feb 24, 2020 at 01:08:13PM -0800, Randy Dunlap wrote:
>> Not trying to be contrary, but I would prefer to keep .rst files as much
>> ASCII as possible.
>
> I don't think anybody is arguing otherwise.  The question is whether
> minusminus should be left as a pair of minus signs or whether it should
> be converted into an en-dash.

FWIW I think a pair of minus signs is never completely wrong in the
output (even when the semantics is en-dash and the conversion is
desirable) but occasionally converting a pair of minus signs to en-dash
is incorrect. Thus retaining the "smart" conversion requires we use some
form of escaping when we don't want double minus to be converted to
en-dash. I'd lean towards "smartquotes = False".

It'll still possible to add Unicode en-dash directly in the .rst if
people really want that.

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Graphics Center