Follow @Openwall on Twitter for new release announcements and other news
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Date: Tue, 23 Apr 2019 16:06:40 -0600
From: Jonathan Corbet <>
To: Borislav Petkov <>
Cc: Mauro Carvalho Chehab <>, Peter Zijlstra
 <>, Mike Snitzer <>, Linux Doc
 Mailing List <>, Mauro Carvalho Chehab
 <>,, Johannes Berg
 <>, Kurt Schwemmer <>,
 Logan Gunthorpe <>, Bjorn Helgaas <>,
 Alasdair Kergon <>,, Kishon Vijay Abraham
 I <>, Rob Herring <>, Mark Rutland
 <>, Bartlomiej Zolnierkiewicz
 <>, David Airlie <>, Daniel Vetter
 <>, Maarten Lankhorst <>,
 Maxime Ripard <>, Sean Paul <>,
 Ning Sun <>, Ingo Molnar <>, Will Deacon
 <>, Alan Stern <>, Andrea Parri
 <>, Boqun Feng <>,
 Nicholas Piggin <>, David Howells <>,
 Jade Alglave <>, Luc Maranget <>,
 "Paul E. McKenney" <>, Akira Yokosawa
 <>, Daniel Lustig <>, "David S. Miller"
 <>, Andreas Färber <>,
 Manivannan Sadhasivam <>, Cornelia Huck
 <>, Farhan Ali <>, Eric Farman
 <>, Halil Pasic <>, Martin
 Schwidefsky <>, Heiko Carstens
 <>, Harry Wei <>, Alex Shi
 <>, Jerry Hoemann <>, Wim
 Van Sebroeck <>, Guenter Roeck <>,
 Thomas Gleixner <>, "H. Peter Anvin" <>,, Russell King <>, Tony Luck
 <>, Fenghua Yu <>, "James E.J.
 Bottomley" <>, Helge Deller
 <>, Yoshinori Sato <>, Rich Felker
 <>, Guan Xuetao <>, Jens Axboe
 <>, Greg Kroah-Hartman <>, "Rafael
 J. Wysocki" <>, Arnd Bergmann <>, Matt
 Mackall <>, Herbert Xu <>, Corey
 Minyard <>, Sumit Semwal <>, Linus
 Walleij <>, Bartosz Golaszewski
 <>, Darren Hart <>, Andy
 Shevchenko <>, Stuart Hayes <>,
 Jaroslav Kysela <>, Alex Williamson
 <>, Kirti Wankhede <>,
 Christoph Hellwig <>, Marek Szyprowski
 <>, Robin Murphy <>, Steffen
 Klassert <>, Kees Cook <>,
 Emese Revfy <>, James Morris <>, "Serge
 E. Hallyn" <>,,,,,,,,,,,,,,,,,,,,,,,,,,, Changbin Du <>
Subject: Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST
 files to *.rst

On Tue, 23 Apr 2019 23:38:16 +0200
Borislav Petkov <> wrote:

> But exactly this - *having* to do rst formatting would mean a lot of
> getting used to and people writing something which is not necessarily
> correct rst and someone else fixing up after them.

Remember that most of our docs are 99% RST even though they were written
by people who had never even heard of RST.  I really don't think it's a
big deal - a far smaller cognitive load than trying to keep up with any
given subsystem's variable-declaration-ordering rules, for example :)

> Another pain point is changing the file paths. Without cscope I would've
> been cursing each time I'm looking for kernel-parameters.txt, for
> example. First of all, it is in Documentation/admin-guide/ now and then
> there's Documentation/admin-guide/kernel-parameters.rst too.

Moving of files has nothing to do with RST, of course.  That you can
blame entirely on me trying to bring some order to Documentation/.  As a
predecessor of mine once put it (

	Documentation/* is a gigantic mess, currently organized based on
	where random passers-by put things down last.

When other parts of the kernel tree turn out to be organized in
less-than-useful ways, we move things around.  I'm trying to do the same
in Documentation/, with an attempt to be sympathetic toward our readers,
sort things by intended audience, and create (someday) a coherent whole.
I agree that moving docs is a short-term annoyance, but I'm hoping that
it brings a long-term benefit.

> So* I'd suggest having as less markup in those files as possible and if
> it is needed, automate adding the needed markup, as Jon suggested.

Minimal markup is the policy (it's even documented :).  Automating stuff
that can be automated is an area that has definitely not received
enough attention; hopefully some things can be done there in the very
near future.



Powered by blists - more mailing lists

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