linux-kernel - Re: [PATCH] Documentation/process/changes: Escape --options to fix Sphinx output

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <87sfcuu0fm.fsf@meer.lwn.net>
Date:   Thu, 20 Apr 2023 07:51:09 -0600
From:   Jonathan Corbet <corbet@....net>
To:     Zipeng Zhang <zhangzipeng0@...mail.com>
Cc:     ojeda@...nel.org, alex.gaynor@...il.com, wedsonaf@...il.com,
        boqun.feng@...il.com, gary@...yguo.net, bjorn3_gh@...tonmail.com,
        nathan@...nel.org, ndesaulniers@...gle.com, trix@...hat.com,
        masahiroy@...nel.org, codeagain@...eagain.dev,
        linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
        rust-for-linux@...r.kernel.org, llvm@...ts.linux.dev,
        Zipeng Zhang <zhangzipeng0@...mail.com>
Subject: Re: [PATCH] Documentation/process/changes: Escape --options to fix
 Sphinx output

Zipeng Zhang <zhangzipeng0@...mail.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@...mail.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