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 >
