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

[Jonathan Corbet <corbet@lwn.net>]

On Tue, 18 Jun 2019 15:56:05 +0100
Valentin Schneider <valentin.schneider@arm.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@arm.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