From mboxrd@z Thu Jan 1 00:00:00 1970 From: Jonathan Corbet Subject: Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst Date: Tue, 23 Apr 2019 16:06:40 -0600 Message-ID: <20190423160640.70c9703f@lwn.net> References: <20190423083135.GA11158@hirez.programming.kicks-ass.net> <20190423125519.GA7104@redhat.com> <20190423130132.GT4038@hirez.programming.kicks-ass.net> <20190423103053.07cf2149@lwn.net> <20190423171158.GG12232@hirez.programming.kicks-ass.net> <20190423172006.GD16353@zn.tnic> <20190423170409.7b1370ac@coco.lan> <20190423213816.GE16353@zn.tnic> Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Return-path: In-Reply-To: <20190423213816.GE16353-Jj63ApZU6fQ@public.gmane.org> List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: iommu-bounces-cunTk1MwBs9QetFLy7KEm3xJsTq8ys+cHZ5vskTnxNA@public.gmane.org Errors-To: iommu-bounces-cunTk1MwBs9QetFLy7KEm3xJsTq8ys+cHZ5vskTnxNA@public.gmane.org To: Borislav Petkov Cc: Mike Snitzer , "Rafael J. Wysocki" , Linus Walleij , Farhan Ali , Will Deacon , dri-devel-PD4FTy7X32lNgt0PjOBp9y5qC8QIuHrW@public.gmane.org, Jaroslav Kysela , Mauro Carvalho Chehab , Christoph Hellwig , linux-arch-u79uwXL29TY76Z2rM5mHXA@public.gmane.org, linux-sh-u79uwXL29TY76Z2rM5mHXA@public.gmane.org, James Morris , Halil Pasic , tboot-devel-5NWGOfrQmneRv+LV9MX5uipxlwaOVQ5f@public.gmane.org, Alan Stern , openipmi-developer-5NWGOfrQmneRv+LV9MX5uipxlwaOVQ5f@public.gmane.org, Guenter Roeck , Boqun Feng , Nicholas Piggin , Alex Williamson , Matt Mackall , Thomas Gleixner , Sean Paul , Greg Kroah-Hartman List-Id: linux-gpio@vger.kernel.org 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 (https://lkml.org/lkml/2007/7/3/422): 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. Thanks, jon