kernel-hardening - Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

Follow @Openwall on Twitter for new release announcements and other news
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <20190423170409.7b1370ac@coco.lan>
Date: Tue, 23 Apr 2019 17:05:02 -0300
From: Mauro Carvalho Chehab <mchehab+samsung@...nel.org>
To: Borislav Petkov <bp@...en8.de>
Cc: Peter Zijlstra <peterz@...radead.org>, Jonathan Corbet <corbet@....net>,
 Mike Snitzer <snitzer@...hat.com>, Linux Doc Mailing List
 <linux-doc@...r.kernel.org>, Mauro Carvalho Chehab <mchehab@...radead.org>,
 linux-kernel@...r.kernel.org, Johannes Berg <johannes@...solutions.net>,
 Kurt Schwemmer <kurt.schwemmer@...rosemi.com>, Logan Gunthorpe
 <logang@...tatee.com>, Bjorn Helgaas <bhelgaas@...gle.com>, Alasdair Kergon
 <agk@...hat.com>, dm-devel@...hat.com, Kishon Vijay Abraham I
 <kishon@...com>, Rob Herring <robh+dt@...nel.org>, Mark Rutland
 <mark.rutland@....com>, Bartlomiej Zolnierkiewicz
 <b.zolnierkie@...sung.com>, David Airlie <airlied@...ux.ie>, Daniel Vetter
 <daniel@...ll.ch>, Maarten Lankhorst <maarten.lankhorst@...ux.intel.com>,
 Maxime Ripard <maxime.ripard@...tlin.com>, Sean Paul <sean@...rly.run>,
 Ning Sun <ning.sun@...el.com>, Ingo Molnar <mingo@...hat.com>, Will Deacon
 <will.deacon@....com>, Alan Stern <stern@...land.harvard.edu>, Andrea Parri
 <andrea.parri@...rulasolutions.com>, Boqun Feng <boqun.feng@...il.com>,
 Nicholas Piggin <npiggin@...il.com>, David Howells <dhowells@...hat.com>,
 Jade Alglave <j.alglave@....ac.uk>, Luc Maranget <luc.maranget@...ia.fr>,
 "Paul E. McKenney" <paulmck@...ux.ibm.com>, Akira Yokosawa
 <akiyks@...il.com>, Daniel Lustig <dlustig@...dia.com>, "David S. Miller"
 <davem@...emloft.net>, Andreas Färber <afaerber@...e.de>,
 Manivannan Sadhasivam <manivannan.sadhasivam@...aro.org>, Cornelia Huck
 <cohuck@...hat.com>, Farhan Ali <alifm@...ux.ibm.com>, Eric Farman
 <farman@...ux.ibm.com>, Halil Pasic <pasic@...ux.ibm.com>, Martin
 Schwidefsky <schwidefsky@...ibm.com>, Heiko Carstens
 <heiko.carstens@...ibm.com>, Harry Wei <harryxiyou@...il.com>, Alex Shi
 <alex.shi@...ux.alibaba.com>, Jerry Hoemann <jerry.hoemann@....com>, Wim
 Van Sebroeck <wim@...ux-watchdog.org>, Guenter Roeck <linux@...ck-us.net>,
 Thomas Gleixner <tglx@...utronix.de>, "H. Peter Anvin" <hpa@...or.com>,
 x86@...nel.org, Russell King <linux@...linux.org.uk>, Tony Luck
 <tony.luck@...el.com>, Fenghua Yu <fenghua.yu@...el.com>, "James E.J.
 Bottomley" <James.Bottomley@...senPartnership.com>, Helge Deller
 <deller@....de>, Yoshinori Sato <ysato@...rs.sourceforge.jp>, Rich Felker
 <dalias@...c.org>, Guan Xuetao <gxt@....edu.cn>, Jens Axboe
 <axboe@...nel.dk>, Greg Kroah-Hartman <gregkh@...uxfoundation.org>, "Rafael
 J. Wysocki" <rafael@...nel.org>, Arnd Bergmann <arnd@...db.de>, Matt
 Mackall <mpm@...enic.com>, Herbert Xu <herbert@...dor.apana.org.au>, Corey
 Minyard <minyard@....org>, Sumit Semwal <sumit.semwal@...aro.org>, Linus
 Walleij <linus.walleij@...aro.org>, Bartosz Golaszewski
 <bgolaszewski@...libre.com>, Darren Hart <dvhart@...radead.org>, Andy
 Shevchenko <andy@...radead.org>, Stuart Hayes <stuart.w.hayes@...il.com>,
 Jaroslav Kysela <perex@...ex.cz>, Alex Williamson
 <alex.williamson@...hat.com>, Kirti Wankhede <kwankhede@...dia.com>,
 Christoph Hellwig <hch@....de>, Marek Szyprowski
 <m.szyprowski@...sung.com>, Robin Murphy <robin.murphy@....com>, Steffen
 Klassert <steffen.klassert@...unet.com>, Kees Cook <keescook@...omium.org>,
 Emese Revfy <re.emese@...il.com>, James Morris <jmorris@...ei.org>, "Serge
 E. Hallyn" <serge@...lyn.com>, linux-wireless@...r.kernel.org,
 linux-pci@...r.kernel.org, devicetree@...r.kernel.org,
 dri-devel@...ts.freedesktop.org, linux-fbdev@...r.kernel.org,
 tboot-devel@...ts.sourceforge.net, linux-arch@...r.kernel.org,
 netdev@...r.kernel.org, linux-arm-kernel@...ts.infradead.org,
 linux-s390@...r.kernel.org, kvm@...r.kernel.org,
 linux-watchdog@...r.kernel.org, linux-ia64@...r.kernel.org,
 linux-parisc@...r.kernel.org, linux-sh@...r.kernel.org,
 sparclinux@...r.kernel.org, linux-block@...r.kernel.org,
 linux-crypto@...r.kernel.org, openipmi-developer@...ts.sourceforge.net,
 linaro-mm-sig@...ts.linaro.org, linux-gpio@...r.kernel.org,
 platform-driver-x86@...r.kernel.org, iommu@...ts.linux-foundation.org,
 linux-mm@...ck.org, kernel-hardening@...ts.openwall.com,
 linux-security-module@...r.kernel.org, Changbin Du <changbin.du@...il.com>
Subject: Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST
 files to *.rst

Em Tue, 23 Apr 2019 19:20:06 +0200
Borislav Petkov <bp@...en8.de> escreveu:

> On Tue, Apr 23, 2019 at 07:11:58PM +0200, Peter Zijlstra wrote:
> > I know I'm an odd duck; but no. They're _less_ accessible for me, as
> > both a reader and author. They look 'funny' when read as a text file
> > (the only way it makes sense to read them; I spend 99% of my time on a
> > computer looking at monospace text interfaces; mutt, vim and console, in
> > that approximate order).  
> 
> +1
> 
> It is probably fine to stare at them here
> https://www.kernel.org/doc/html/latest/ and the end result is good
> for showing them in browsers but after this conversion, it is
> getting more and more painful to work with those files. For example,
> Documentation/x86/x86_64/mm.txt we use a lot. I'd hate it if I had to go
> sort out rest muck first just so that I can read it.

That's my view about how that specific file would be after
converted to ReST:

	https://git.linuxtv.org/mchehab/experimental.git/tree/Documentation/x86/x86_64/mm.rst?h=convert_rst_renames

I don't have any troubles reading/understanding it as a plain text
file, and its html output is also nice (although Sphinx 1.7.8 seems to
have some issues when parsing some cells - probably due to some bug):

	https://www.infradead.org/~mchehab/rst_conversion/x86/x86_64/mm.html

> 
> I think we can simply leave some text files be text files and be done
> with it.

Changbin's approach was somewhat close to what you want. He simply
prepended the tables with ::, in order to show them as plain old
ascii:

	https://lore.kernel.org/lkml/20190423162932.21428-60-changbin.du@gmail.com/

Both equally works, from ReST conversion PoV. I'm fine ether way.

I prefer my approach, as, IMHO, it is visually nicer on both text and
html versions, but his approach is likely easier to maintain, as doing
ascii artwork by hand is sometimes painful.

Thanks,
Mauro
Confused about mailing lists and their use? Read about mailing lists on Wikipedia and check out these guidelines on proper formatting of your messages.