kernel-hardening - Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main dir

Follow @Openwall on Twitter for new release announcements and other news
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <20190619072218.4437f891@coco.lan>
Date: Wed, 19 Jun 2019 07:22:18 -0300
From: Mauro Carvalho Chehab <mchehab+samsung@...nel.org>
To: Daniel Vetter <daniel@...ll.ch>
Cc: Linux Doc Mailing List <linux-doc@...r.kernel.org>, Mauro Carvalho
 Chehab <mchehab@...radead.org>, Linux Kernel Mailing List
 <linux-kernel@...r.kernel.org>, Jonathan Corbet <corbet@....net>, Johannes
 Berg <johannes@...solutions.net>, Kurt Schwemmer
 <kurt.schwemmer@...rosemi.com>, Logan Gunthorpe <logang@...tatee.com>,
 Bjorn Helgaas <bhelgaas@...gle.com>, Alan Stern
 <stern@...land.harvard.edu>, Andrea Parri
 <andrea.parri@...rulasolutions.com>, Will Deacon <will.deacon@....com>,
 Peter Zijlstra <peterz@...radead.org>, 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>, Stuart Hayes
 <stuart.w.hayes@...il.com>, Thomas Gleixner <tglx@...utronix.de>, Ingo
 Molnar <mingo@...hat.com>, Darren Hart <dvhart@...radead.org>, Kees Cook
 <keescook@...omium.org>, Emese Revfy <re.emese@...il.com>, Ohad Ben-Cohen
 <ohad@...ery.com>, Bjorn Andersson <bjorn.andersson@...aro.org>, Corey
 Minyard <minyard@....org>, Marc Zyngier <marc.zyngier@....com>, William
 Breathitt Gray <vilhelm.gray@...il.com>, Jaroslav Kysela <perex@...ex.cz>,
 Greg Kroah-Hartman <gregkh@...uxfoundation.org>, "Rafael J. Wysocki"
 <rafael@...nel.org>, "Naveen N. Rao" <naveen.n.rao@...ux.ibm.com>, Anil S
 Keshavamurthy <anil.s.keshavamurthy@...el.com>, "David S. Miller"
 <davem@...emloft.net>, Masami Hiramatsu <mhiramat@...nel.org>, Johannes
 Thumshirn <morbidrsa@...il.com>, Steffen Klassert
 <steffen.klassert@...unet.com>, Sudip Mukherjee
 <sudipm.mukherjee@...il.com>, Andreas Färber
 <afaerber@...e.de>, Manivannan Sadhasivam
 <manivannan.sadhasivam@...aro.org>, Rodolfo Giometti
 <giometti@...eenne.com>, Richard Cochran <richardcochran@...il.com>,
 Thierry Reding <thierry.reding@...il.com>, Sumit Semwal
 <sumit.semwal@...aro.org>, Gustavo Padovan <gustavo@...ovan.org>, Jens
 Wiklander <jens.wiklander@...aro.org>, Kirti Wankhede
 <kwankhede@...dia.com>, Alex Williamson <alex.williamson@...hat.com>,
 Cornelia Huck <cohuck@...hat.com>, Bartlomiej Zolnierkiewicz
 <b.zolnierkie@...sung.com>, David Airlie <airlied@...ux.ie>, Maarten
 Lankhorst <maarten.lankhorst@...ux.intel.com>, Maxime Ripard
 <maxime.ripard@...tlin.com>, Sean Paul <sean@...rly.run>, Farhan Ali
 <alifm@...ux.ibm.com>, Eric Farman <farman@...ux.ibm.com>, Halil Pasic
 <pasic@...ux.ibm.com>, Heiko Carstens <heiko.carstens@...ibm.com>, Vasily
 Gorbik <gor@...ux.ibm.com>, Christian Borntraeger <borntraeger@...ibm.com>,
 Harry Wei <harryxiyou@...il.com>, Alex Shi <alex.shi@...ux.alibaba.com>,
 Evgeniy Polyakov <zbr@...emap.net>, Jerry Hoemann <jerry.hoemann@....com>,
 Wim Van Sebroeck <wim@...ux-watchdog.org>, Guenter Roeck
 <linux@...ck-us.net>, Guan Xuetao <gxt@....edu.cn>, Arnd Bergmann
 <arnd@...db.de>, Linus Walleij <linus.walleij@...aro.org>, Bartosz
 Golaszewski <bgolaszewski@...libre.com>, Andy Shevchenko
 <andy@...radead.org>, Jiri Slaby <jslaby@...e.com>,
 linux-wireless@...r.kernel.org, Linux PCI <linux-pci@...r.kernel.org>,
 "open list:GENERIC INCLUDE/A..." <linux-arch@...r.kernel.org>,
 platform-driver-x86@...r.kernel.org, Kernel Hardening
 <kernel-hardening@...ts.openwall.com>, linux-remoteproc@...r.kernel.org,
 openipmi-developer@...ts.sourceforge.net, linux-crypto@...r.kernel.org,
 Linux ARM <linux-arm-kernel@...ts.infradead.org>, netdev
 <netdev@...r.kernel.org>, linux-pwm <linux-pwm@...r.kernel.org>, dri-devel
 <dri-devel@...ts.freedesktop.org>, kvm@...r.kernel.org, Linux Fbdev
 development list <linux-fbdev@...r.kernel.org>, linux-s390@...r.kernel.org,
 linux-watchdog@...r.kernel.org, "moderated list:DMA BUFFER SHARING
 FRAMEWORK" <linaro-mm-sig@...ts.linaro.org>, linux-gpio
 <linux-gpio@...r.kernel.org>, Linux MM <linux-mm@...ck.org>
Subject: Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main
 dir

Hi Daniel,

Em Wed, 19 Jun 2019 11:05:57 +0200
Daniel Vetter <daniel@...ll.ch> escreveu:

> On Tue, Jun 18, 2019 at 10:55 PM Mauro Carvalho Chehab
> <mchehab+samsung@...nel.org> wrote:
> > diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst
> > index fa30dfcfc3c8..b0f948d8733b 100644
> > --- a/Documentation/gpu/drm-mm.rst
> > +++ b/Documentation/gpu/drm-mm.rst
> > @@ -320,7 +320,7 @@ struct :c:type:`struct file_operations <file_operations>` get_unmapped_area
> >  field with a pointer on :c:func:`drm_gem_cma_get_unmapped_area`.
> >
> >  More detailed information about get_unmapped_area can be found in
> > -Documentation/nommu-mmap.rst
> > +Documentation/driver-api/nommu-mmap.rst  
> 
> Random drive-by comment: Could we convert these into hyperlinks within
> sphinx somehow, without making them less useful as raw file references
> (with vim I can just type 'gf' and it works, emacs probably the same).
> -Daniel

Short answer: I don't know how vim/emacs would recognize Sphinx tags.

There are two ways of doing hyperlinks to local files. The first one is to 
add a label at the other file and use a reference to such label, e. g. at
nommu-mmap.rst, you would add a label like:

	.. _drm_nommu-mmap:

at the beginning of the file.

Then, at drm-mm.rst, you would use :ref:`drm_nommu-mmap` (there are a
few other alternative tags that would work the same way).

The advantage is that you could move/rename documents anytime, without
needing to take care of it.

Perhaps it could be possible a tool like cscope to parse those in
order to provide such automation for Sphinx. I dunno.

-

The other way is to use:

	:doc:`nommu-mmap.rst` (if both files are at the same dir)

The :doc: path is the current directory. So, if a file at, let's say,
Documentation/gpu wants to refer another file at driver-api, it would
need to write it as:

	:doc:`../driver-api/nommu-mmap.rst`

I'm not sure if vim/emacs recognizes this syntax, though.

Perhaps this tag could be used as:

	:doc:`Documentation/driver-api/nommu-mmap.rst <../driver-api/nommu-map.rst`

But that looks too ugly to my taste.

-

On this conversion, I opted to not touch this. We may consider trying
to replace those 


Thanks,
Mauro
Confused about mailing lists and their use? Read about mailing lists on Wikipedia and check out these guidelines on proper formatting of your messages.