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: <1b60185d-1fb4-b8f0-c7c2-9fb50f550566@arm.com>
Date:   Tue, 18 Jun 2019 16:51:06 +0100
From:   Valentin Schneider <valentin.schneider@....com>
To:     Jonathan Corbet <corbet@....net>
Cc:     linux-kernel@...r.kernel.org, linux-doc@...r.kernel.org
Subject: Re: [PATCH] docs/vm: hwpoison.rst: Fix quote formatting

On 18/06/2019 16:31, Jonathan Corbet wrote:
> 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...:)
> 

I'm afraid this was only a "drive-by" patch, as I just happened to skim
through this page on my phone while waiting for a meeting - I'm quite
clueless about page poisoning.

However, I could try to replace the quote with a kernel-doc directive to
get a more up-to-date description (and maybe add a small note to say the
rest of the doc is somewhat outdated). That, or just keep the quote as is
but keep the asterisks - whichever you're happier with.

> Thanks,
> 
> jon
>