Zipeng Zhang <[email protected]> writes:
> Add an escape character to resolve the problem of
> "--version" being displayed as "–version".
>
> Without such escaping, -- is rendered as – (en dash).
>
> Signed-off-by: Zipeng Zhang <[email protected]>
> ---
> Documentation/process/changes.rst | 38 +++++++++++++++----------------
> 1 file changed, 19 insertions(+), 19 deletions(-)
Thanks for working on improving the documentation!
I understand where you are coming from, but this may be one of those
cases where the readability of the plain-text documentation has to win
out. Those backslashes are ugly and seem unlikely to be maintained
going forward.
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.
Thanks,
jon
Jonathan Corbet <[email protected]> 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 <[email protected]>
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.
Reported-by: Zipeng Zhang <[email protected]>
Link: https://lore.kernel.org/lkml/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>
---
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
On Thu, Apr 20, 2023 at 5:40 PM Jonathan Corbet <[email protected]> wrote:
>
> 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.
I think it was deprecated in v1.6, and removed in v1.7. There seems to
be code for printing a deprecation warning during v1.6, though.
> +# If true, Docutils "smart quotes will be used to convert quotes and dashes
Missing quote in "smart quotes"? Or maybe Saxon genitive?
Other than that, sounds good to me!
Reviewed-by: Miguel Ojeda <[email protected]>
Cheers,
Miguel
[Dropped most CCs]
Hi Jon,
On Thu, 20 Apr 2023 09:40:39 -0600, Jonathan Corbet wrote:
> Jonathan Corbet <[email protected]> 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 <[email protected]>
> 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/[email protected]/
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 <[email protected]>
> Link: https://lore.kernel.org/lkml/[email protected]
> Signed-off-by: Jonathan Corbet <[email protected]>
> ---
> 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
Akira Yokosawa <[email protected]> writes:
> Whereas the summary reads "docs: turn off "smart quotes" in the HTML build",
> the change is also effective in the LaTeX/PDF build.
True...so the title is a bit off, but it is a fix for that build too,
right?
> BTW, Jon, don't you test build pdfdocs these days?
I will confess that I don't do it as often as I should. As you may have
noticed, it takes a little while to run, and the interest in PDF output
is pretty low 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/[email protected]/
Media docs patches normally go through the media tree, just like the
original bug did; I had assumed that would happen here as well.
Seemingly not, so I've just picked those patches up into docs-next.
> 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.
Interest is low, but not zero, and I'd prefer to keep it working. It
really helps when somebody tells me that it breaks (it is rather
fragile, alas)!
One of these days I would really like to make a serious attempt to see
if rst2pdf has any hope of ever working for us. Taking latex out of the
picture would simplify so many things.
Thanks,
jon