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 20:21:43 +0200
From: Peter Zijlstra <peterz@...radead.org>
To: Jonathan Corbet <corbet@....net>
Cc: Mike Snitzer <snitzer@...hat.com>,
	Mauro Carvalho Chehab <mchehab+samsung@...nel.org>,
	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

On Tue, Apr 23, 2019 at 11:53:49AM -0600, Jonathan Corbet 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.

The funny thing is; that sentence continues (on a new line) like:

"friends are traced and the pointers, together with additional"

So while it then has cross-references to a few functions, all 'friends'
are left dangling. So what's the point of the cross-references?

Also, 'make ctags' and follow tag (ctrl-] for fellow vim users) will get
you to the function, no magic markup required.

> 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.

That would be good; less markup is more.

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.