* [PATCH] Documentation/process/changes: Escape --options to fix Sphinx output
@ 2023-04-20 10:21 Zipeng Zhang
2023-04-20 13:51 ` Jonathan Corbet
0 siblings, 1 reply; 4+ messages in thread
From: Zipeng Zhang @ 2023-04-20 10:21 UTC (permalink / raw)
To: corbet
Cc: ojeda, alex.gaynor, wedsonaf, boqun.feng, gary, bjorn3_gh,
nathan, ndesaulniers, trix, masahiroy, codeagain, linux-doc,
linux-kernel, rust-for-linux, llvm, Zipeng Zhang
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 <zhangzipeng0@foxmail.com>
---
Documentation/process/changes.rst | 38 +++++++++++++++----------------
1 file changed, 19 insertions(+), 19 deletions(-)
diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst
index ef540865ad22..2d2747e1964a 100644
--- a/Documentation/process/changes.rst
+++ b/Documentation/process/changes.rst
@@ -29,17 +29,17 @@ you probably needn't concern yourself with pcmciautils.
====================== =============== ========================================
Program Minimal version Command to check the version
====================== =============== ========================================
-GNU C 5.1 gcc --version
-Clang/LLVM (optional) 11.0.0 clang --version
-Rust (optional) 1.62.0 rustc --version
-bindgen (optional) 0.56.0 bindgen --version
-GNU make 3.82 make --version
-bash 4.2 bash --version
+GNU C 5.1 gcc \--version
+Clang/LLVM (optional) 11.0.0 clang \--version
+Rust (optional) 1.62.0 rustc \--version
+bindgen (optional) 0.56.0 bindgen \--version
+GNU make 3.82 make \--version
+bash 4.2 bash \--version
binutils 2.25 ld -v
-flex 2.5.35 flex --version
-bison 2.0 bison --version
-pahole 1.16 pahole --version
-util-linux 2.10o fdformat --version
+flex 2.5.35 flex \--version
+bison 2.0 bison \--version
+pahole 1.16 pahole \--version
+util-linux 2.10o fdformat \--version
kmod 13 depmod -V
e2fsprogs 1.41.4 e2fsck -V
jfsutils 1.1.3 fsck.jfs -V
@@ -49,17 +49,17 @@ 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
-udev 081 udevd --version
-grub 0.93 grub --version || grub-install --version
-mcelog 0.6 mcelog --version
+PPP 2.4.0 pppd \--version
+nfs-utils 1.0.5 showmount \--version
+procps 3.2.0 ps \--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.7 sphinx-build --version
-cpio any cpio --version
+bc 1.06.95 bc \--version
+Sphinx\ [#f1]_ 1.7 sphinx-build \--version
+cpio any cpio \--version
====================== =============== ========================================
.. [#f1] Sphinx is needed only to build the Kernel documentation
--
2.39.2
^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [PATCH] Documentation/process/changes: Escape --options to fix Sphinx output
2023-04-20 10:21 [PATCH] Documentation/process/changes: Escape --options to fix Sphinx output Zipeng Zhang
@ 2023-04-20 13:51 ` Jonathan Corbet
2023-04-20 15:40 ` Jonathan Corbet
0 siblings, 1 reply; 4+ messages in thread
From: Jonathan Corbet @ 2023-04-20 13:51 UTC (permalink / raw)
To: Zipeng Zhang
Cc: ojeda, alex.gaynor, wedsonaf, boqun.feng, gary, bjorn3_gh,
nathan, ndesaulniers, trix, masahiroy, codeagain, linux-doc,
linux-kernel, rust-for-linux, llvm, Zipeng Zhang
Zipeng Zhang <zhangzipeng0@foxmail.com> 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 <zhangzipeng0@foxmail.com>
> ---
> 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
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH] Documentation/process/changes: Escape --options to fix Sphinx output
2023-04-20 13:51 ` Jonathan Corbet
@ 2023-04-20 15:40 ` Jonathan Corbet
2023-04-20 17:16 ` Miguel Ojeda
0 siblings, 1 reply; 4+ messages in thread
From: Jonathan Corbet @ 2023-04-20 15:40 UTC (permalink / raw)
To: Zipeng Zhang
Cc: ojeda, alex.gaynor, wedsonaf, boqun.feng, gary, bjorn3_gh,
nathan, ndesaulniers, trix, masahiroy, codeagain, linux-doc,
linux-kernel, rust-for-linux, llvm, Zipeng Zhang
Jonathan Corbet <corbet@lwn.net> 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 <corbet@lwn.net>
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 <zhangzipeng0@foxmail.com>
Link: https://lore.kernel.org/lkml/tencent_CB1A298D31FD221496FF657CD7EF406E6605@qq.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
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
^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [PATCH] Documentation/process/changes: Escape --options to fix Sphinx output
2023-04-20 15:40 ` Jonathan Corbet
@ 2023-04-20 17:16 ` Miguel Ojeda
0 siblings, 0 replies; 4+ messages in thread
From: Miguel Ojeda @ 2023-04-20 17:16 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Zipeng Zhang, ojeda, alex.gaynor, wedsonaf, boqun.feng, gary,
bjorn3_gh, nathan, ndesaulniers, trix, masahiroy, codeagain,
linux-doc, linux-kernel, rust-for-linux, llvm
On Thu, Apr 20, 2023 at 5:40 PM Jonathan Corbet <corbet@lwn.net> 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 <ojeda@kernel.org>
Cheers,
Miguel
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2023-04-20 17:17 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-04-20 10:21 [PATCH] Documentation/process/changes: Escape --options to fix Sphinx output Zipeng Zhang
2023-04-20 13:51 ` Jonathan Corbet
2023-04-20 15:40 ` Jonathan Corbet
2023-04-20 17:16 ` Miguel Ojeda
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).