linux-kernel - Re: [PATCH] docs/vm: hwpoison.rst: Fix quote formatting

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: <20190618093159.26352aed@lwn.net>
Date:   Tue, 18 Jun 2019 09:31:59 -0600
From:   Jonathan Corbet <corbet@....net>
To:     Valentin Schneider <valentin.schneider@....com>
Cc:     linux-kernel@...r.kernel.org, linux-doc@...r.kernel.org
Subject: Re: [PATCH] docs/vm: hwpoison.rst: Fix quote formatting

On Tue, 18 Jun 2019 15:56:05 +0100
Valentin Schneider <valentin.schneider@....com> wrote:

> The asterisks prepended to the quoted text currently get translated to
> bullet points, which gets increasingly confusing the smaller your
> screen is (when viewing the sphinx output, that is).
> 
> Convert the whole quote to a literal block.
> 
> Signed-off-by: Valentin Schneider <valentin.schneider@....com>

That definitely seems worth fixing, and I can apply this.  But a few
things to ponder first...

 - If you convert it to a literal block, the asterisks can remain, making
   for a less intrusive patch.

 - I was wondering if we should just use a kernel-doc directive to pull
   the comment directly from the source, but investigation quickly showed
   that the "overview comment" doesn't actually exist in anything close to
   the quoted form.  See mm/memory-failure.c.

Given that, and things like references to support in "upcoming Intel
CPUs", I suspect that this document is pretty seriously out of date and
needs some more in-depth attention.  If you're playing in this area and
feel like it, updating the document for real would be much appreciated...:)

Thanks,

jon