linux-kernel - Re: [PATCH] docs: Fix backticks in README instructions

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] [day] [month] [year] [list]

Message-ID: <87tt9sf088.fsf@trenco.lwn.net>
Date: Tue, 21 Jan 2025 12:14:31 -0700
From: Jonathan Corbet <corbet@....net>
To: Akira Yokosawa <akiyks@...il.com>, carlodelos90@...il.com
Cc: linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org, Akira Yokosawa
 <akiyks@...il.com>
Subject: Re: [PATCH] docs: Fix backticks in README instructions

Akira Yokosawa <akiyks@...il.com> writes:

> carlodelos90 wrote:
>> The commands `make pdfdocs` and `make htmldocs` were incorrectly formatted
>> with only two backticks, which caused confusion and didn't render properly
>> in some contexts.
>
> Do you mean:
>
> ... One example is GitHub where top-level README is assumed to be in
> the GitHub dialect of Markdown.
>
> ???

Indeed, "some contexts" is a uselessly vague description; please say
what the actual problem is.

>>                   This change updates the documentation to use triple
>> backticks for consistency and clarity.
>
> Obviously, triple backticks don't work in other contexts.
>
> So your "fix" breaks assumption of others.
>
> I think GitHub can render its README pane in reST format if you add a
> symlink of README.rst -> README.  No?

The thing is ... *we* don't render that file as RST either.  So perhaps
the best solution is just to use normal "quotes" rather than any sort of
markup?

Thanks,

jon