Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
From:   Jonathan Corbet <corbet@lwn.net>
To:     Zipeng Zhang <zhangzipeng0@foxmail.com>
Cc:     ojeda@kernel.org, alex.gaynor@gmail.com, wedsonaf@gmail.com,
        boqun.feng@gmail.com, gary@garyguo.net, bjorn3_gh@protonmail.com,
        nathan@kernel.org, ndesaulniers@google.com, trix@redhat.com,
        masahiroy@kernel.org, codeagain@codeagain.dev,
        linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        rust-for-linux@vger.kernel.org, llvm@lists.linux.dev,
        Zipeng Zhang <zhangzipeng0@foxmail.com>
Subject: Re: [PATCH] Documentation/process/changes: Escape --options to fix
 Sphinx output
In-Reply-To: <tencent_CB1A298D31FD221496FF657CD7EF406E6605@qq.com>
References: <tencent_CB1A298D31FD221496FF657CD7EF406E6605@qq.com>
Date:   Thu, 20 Apr 2023 07:51:09 -0600
Message-ID: <87sfcuu0fm.fsf@meer.lwn.net>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
Precedence: bulk

Zipeng Zhang <zhangzipeng0@foxmail.com> writes:

> Add an escape character to resolve the problem of
> "--version" being displayed as "=E2=80=93version".
>
> Without such escaping, -- is rendered as =E2=80=93 (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