[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <20190423171944.7ac6db54@coco.lan>
Date: Tue, 23 Apr 2019 17:19:44 -0300
From: Mauro Carvalho Chehab <mchehab+samsung@...nel.org>
To: Jonathan Corbet <corbet@....net>
Cc: Peter Zijlstra <peterz@...radead.org>, 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>, Borislav Petkov <bp@...en8.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
Subject: Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST
files to *.rst
Em Tue, 23 Apr 2019 11:53:49 -0600
Jonathan Corbet <corbet@....net> escreveu:
> On Tue, 23 Apr 2019 19:11:58 +0200
> Peter Zijlstra <peterz@...radead.org> 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
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.
