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

[Valentin Schneider]

On 18/06/2019 16:31, Jonathan Corbet wrote:
> On Tue, 18 Jun 2019 15:56:05 +0100
> Valentin Schneider <valentin.schneider@xxxxxxx> 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@xxxxxxx>
> 
> 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
>