From mboxrd@z Thu Jan 1 00:00:00 1970 Date: Tue, 23 Apr 2019 17:19:44 -0300 From: Mauro Carvalho Chehab Subject: Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst Message-ID: <20190423171944.7ac6db54@coco.lan> In-Reply-To: <20190423115349.589c3d50@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> <20190423115349.589c3d50@lwn.net> MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit To: Jonathan Corbet Cc: Peter Zijlstra , Mike Snitzer , Linux Doc Mailing List , Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Johannes Berg , Kurt Schwemmer , Logan Gunthorpe , Bjorn Helgaas , Alasdair Kergon , dm-devel@redhat.com, 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 =?UTF-8?B?RsOkcmJlcg==?= , 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 , Borislav Petkov , "H. Peter Anvin" , x86@kernel.org, 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" , linux-wireless@vger.kernel.org, linux-pci@vger.kernel.org, devicetree@vger.kernel.org, dri-devel@lists.freedesktop.org, linux-fbdev@vger.kernel.org, tboot-devel@lists.sourceforge.net, linux-arch@vger.kernel.org, netdev@vger.kernel.org, linux-arm-kernel@lists.infradead.org, linux-s390@vger.kernel.org, kvm@vger.kernel.org, linux-watchdog@vger.kernel.org, linux-ia64@vger.kernel.org, linux-parisc@vger.kernel.org, linux-sh@vger.kernel.org, sparclinux@vger.kernel.org, linux-block@vger.kernel.org, linux-crypto@vger.kernel.org, openipmi-developer@lists.sourceforge.net, linaro-mm-sig@lists.linaro.org, linux-gpio@vger.kernel.org, platform-driver-x86@vger.kernel.org, iommu@lists.linux-foundation.org, linux-mm@kvack.org, kernel-hardening@lists.openwall.com, linux-security-module@vger.kernel.org List-ID: Em Tue, 23 Apr 2019 11:53:49 -0600 Jonathan Corbet escreveu: > On Tue, 23 Apr 2019 19:11:58 +0200 > Peter Zijlstra wrote: > > > Look at crap like this: > > > > "The memory allocations via :c:func:`kmalloc`, :c:func:`vmalloc`, > > :c:func:`kmem_cache_alloc` and" > > > > That should've been written like: > > > > "The memory allocations via kmalloc(), vmalloc(), kmem_cache_alloc() > > and" > > Yeah, I get it. That markup generates cross-references, which can be > seriously useful for readers - we want that. But I do wonder if we > couldn't do it automatically with just a little bit of scripting work. > It's not to hard to recognize this_is_a_function(), after all. I'll look > into that, it would definitely help to remove some gunk from the source > docs. While on it, one thing that I noticed on several documents is that they reference other documents by their names. On this conversion, I avoided replacing that by a :ref:`` tag or a :doc:`` tag. I only added cross references on two cases: - a latex file that got converted to ReST and had such cross-references already; - one of the document sets that seemed to be using some other markup language very close to ReST, but with a different cross-reference markup. So, I just converted it to use the syntax that Sphinx would recognize. Anyway, one of the things that occurred to me is that maybe some scripting work or a ReST extension could do something to parse "Documentation/foo" as :doc:`Documentation/foo` without needing to explicitly use any ReST specific tags. Thanks, Mauro