From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mauro Carvalho Chehab Subject: Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst Date: Tue, 23 Apr 2019 17:19:44 -0300 Message-ID: <20190423171944.7ac6db54@coco.lan> 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 Return-path: In-Reply-To: <20190423115349.589c3d50-T1hC0tSOHrs@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: Jonathan Corbet Cc: Mike Snitzer , "Rafael J. Wysocki" , Linus Walleij , Farhan Ali , Will Deacon , dri-devel-PD4FTy7X32lNgt0PjOBp9y5qC8QIuHrW@public.gmane.org, Jaroslav Kysela , kernel-hardening-ZwoEplunGu1jrUoiu81ncdBPR1lH4CV8@public.gmane.org, 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 , linux-wireless@v List-Id: linux-gpio@vger.kernel.org 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