Re: [PATCH v2 09/11] docs: Fix some broken references

From: Andrea Parri <parri.andrea@gmail.com>
To: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Cc: Catalin Marinas <catalin.marinas@arm.com>,
	Linus Walleij <linus.walleij@linaro.org>,
	Will Deacon <will.deacon@arm.com>,
	dri-devel@lists.freedesktop.org, Jaroslav Kysela <perex@perex.cz>,
	Eric Paris <eparis@parisplace.org>,
	linux-clk@vger.kernel.org, James Morris <jmorris@namei.org>,
	Alan Stern <stern@rowland.harvard.edu>,
	xen-devel@lists.xenproject.org, Boqun Feng <boqun.feng@gmail.com>,
	Nicholas Piggin <npiggin@gmail.com>,
	Sean Paul <seanpaul@chromium.org>,
	Thomas Gleixner <tglx@linutronix.de>,
	Antoine Jacquet <royale@zerezo.com>,
	Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
	linux-usb@vger.kernel.org, linux-kernel@vger.kernel.org,
	Li Zefan <lizefan@huawei.com>,
	linux-crypto@vger.kernel.org, Mark Rutland <mark.rutland@arm.com>,
	alsa-devel@alsa-project.org,
	Linux Doc Mailing List <linux-doc@vger.kernel.org>,
	David Airlie <airlied@linux.ie>, Gustavo Padovan <gustavo@pa>
Subject: Re: [PATCH v2 09/11] docs: Fix some broken references
Date: Wed, 9 May 2018 21:20:32 +0200	[thread overview]
Message-ID: <20180509192032.GA2788@andrea> (raw)
In-Reply-To: <20180509152045.722f0c51@vento.lan>

On Wed, May 09, 2018 at 03:20:45PM -0300, Mauro Carvalho Chehab wrote:
> Em Wed, 9 May 2018 19:15:01 +0200
> Andrea Parri <parri.andrea@gmail.com> escreveu:
> 
> > On Wed, May 09, 2018 at 10:18:52AM -0300, Mauro Carvalho Chehab wrote:
> > > As we move stuff around, some doc references are broken. Fix some of
> > > them via this script:
> > > 	./scripts/documentation-file-ref-check --fix-rst
> > > 
> > > Manually checked if the produced result is valid, removing a few
> > > false-positives.
> > > 
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>  
> > 
> > Thank you again for doing this,
> > 
> > 
> > > ---
> > >  .../admin-guide/kernel-parameters.txt         |  4 ++--
> > >  .../bindings/input/rotary-encoder.txt         |  2 +-
> > >  Documentation/driver-api/gpio/consumer.rst    |  2 +-
> > >  Documentation/kprobes.txt                     |  4 ++--
> > >  Documentation/trace/coresight.txt             |  2 +-
> > >  Documentation/trace/events.rst                |  2 +-
> > >  Documentation/trace/ftrace-uses.rst           |  2 +-
> > >  Documentation/trace/histogram.txt             |  2 +-
> > >  Documentation/trace/intel_th.rst              |  2 +-
> > >  Documentation/trace/tracepoint-analysis.rst   |  6 +++---
> > >  Documentation/translations/ja_JP/howto.rst    |  4 ++--
> > >  .../translations/zh_CN/magic-number.txt       |  4 ++--
> > >  .../zh_CN/video4linux/omap3isp.txt            |  4 ++--
> > >  MAINTAINERS                                   | 20 +++++++++----------
> > >  arch/Kconfig                                  |  2 +-
> > >  arch/arm/include/asm/cacheflush.h             |  2 +-
> > >  arch/arm64/include/asm/cacheflush.h           |  2 +-
> > >  arch/microblaze/include/asm/cacheflush.h      |  2 +-
> > >  arch/um/Kconfig.um                            |  2 +-
> > >  arch/unicore32/include/asm/cacheflush.h       |  2 +-
> > >  arch/x86/entry/vsyscall/vsyscall_64.c         |  2 +-
> > >  arch/xtensa/include/asm/cacheflush.h          |  4 ++--
> > >  block/Kconfig                                 |  2 +-
> > >  certs/Kconfig                                 |  2 +-
> > >  crypto/asymmetric_keys/asymmetric_type.c      |  2 +-
> > >  crypto/asymmetric_keys/signature.c            |  2 +-
> > >  drivers/char/Kconfig                          |  2 +-
> > >  drivers/clk/clk.c                             |  4 ++--
> > >  drivers/clk/ingenic/cgu.h                     |  2 +-
> > >  drivers/gpu/vga/Kconfig                       |  2 +-
> > >  drivers/gpu/vga/vgaarb.c                      |  2 +-
> > >  drivers/input/joystick/Kconfig                | 10 +++++-----
> > >  drivers/input/joystick/iforce/Kconfig         |  2 +-
> > >  drivers/input/joystick/walkera0701.c          |  2 +-
> > >  drivers/input/misc/Kconfig                    |  4 ++--
> > >  drivers/input/misc/rotary_encoder.c           |  2 +-
> > >  drivers/input/mouse/Kconfig                   |  6 +++---
> > >  drivers/input/mouse/alps.c                    |  2 +-
> > >  drivers/input/touchscreen/wm97xx-core.c       |  2 +-
> > >  drivers/lightnvm/pblk-rb.c                    |  2 +-
> > >  drivers/md/bcache/Kconfig                     |  2 +-
> > >  drivers/md/bcache/btree.c                     |  2 +-
> > >  drivers/md/bcache/extents.c                   |  2 +-
> > >  drivers/media/dvb-core/dvb_ringbuffer.c       |  2 +-
> > >  drivers/media/pci/meye/Kconfig                |  2 +-
> > >  drivers/media/platform/pxa_camera.c           |  4 ++--
> > >  .../soc_camera/sh_mobile_ceu_camera.c         |  2 +-
> > >  drivers/media/radio/Kconfig                   |  2 +-
> > >  drivers/media/radio/si470x/Kconfig            |  2 +-
> > >  drivers/media/usb/dvb-usb-v2/lmedm04.c        |  2 +-
> > >  drivers/media/usb/zr364xx/Kconfig             |  2 +-
> > >  drivers/parport/Kconfig                       |  6 +++---
> > >  drivers/staging/media/bcm2048/TODO            |  2 +-
> > >  include/keys/asymmetric-subtype.h             |  2 +-
> > >  include/keys/asymmetric-type.h                |  2 +-
> > >  include/linux/assoc_array.h                   |  2 +-
> > >  include/linux/assoc_array_priv.h              |  2 +-
> > >  include/linux/circ_buf.h                      |  2 +-
> > >  include/linux/ftrace.h                        |  2 +-
> > >  include/linux/rculist_nulls.h                 |  2 +-
> > >  include/uapi/linux/prctl.h                    |  2 +-
> > >  include/xen/interface/io/kbdif.h              |  2 +-
> > >  kernel/cgroup/cpuset.c                        |  2 +-
> > >  kernel/trace/Kconfig                          | 16 +++++++--------
> > >  lib/Kconfig                                   |  2 +-
> > >  security/selinux/hooks.c                      |  2 +-
> > >  sound/core/Kconfig                            |  4 ++--
> > >  sound/drivers/Kconfig                         |  4 ++--
> > >  sound/pci/Kconfig                             | 10 +++++-----
> > >  tools/include/uapi/linux/prctl.h              |  2 +-
> > >  tools/lib/api/fs/fs.c                         |  2 +-
> 
> 
> > >  tools/memory-model/README                     | 10 +++++-----  
> > 
> > As mentioned in the previous thread, I am for keeping the current
> > references: the REAMDE is listing the doc files, as well as other
> > files in tools/memory-model/, relatively to that directory.
> 
> Yeah, at least this hunk deserves some rework, as now some
> references are Documentation/.../foo, while others are just
> bar.
> 
> As on (almost) all other places (except for tools/memory-model/README),
> the references are always from the main directory, I would make all
> patches there also relative to main dir. If you're afraid of
> not being too clearer, we could prefix all of them with something
> like:

Actually, another place is (consistently):

   tools/memory-model/litmus-tests/README

Sorry, but we are not going to replace:

  ISA2+pooncerelease+poacquirerelease+poacquireonce.litmus

with

   tools/memory-model/litmus-tests/README/ISA2+pooncerelease+poacquirerelease+poacquireonce.litmus

or

   ${LINUX}/tools/memory-model/litmus-tests/README/ISA2+pooncerelease+poacquirerelease+poacquireonce.litmus

(for the obvious reason; and if you're thinking at "just rename the test"
 I anticipate a long discussion on naming schemes and related tools ...).

  Andrea

> 
> 	${LINUX}/tools/memory-model/...
> 
> just like some DT binding files do:
> 
> 	Documentation/devicetree/bindings/sound/audio-graph-card.txt:see ${LINUX}/Documentation/devicetree/bindings/graph.txt
> 
> A bonus of doing that is that the broken reference detect script can
> keep parsing it without changes (well, it wouldn't be hard to make
> it also accept a relative file, but doing that just due to 
> tools/memory-model/README seems overkill).
> 
> Another advantage is that it would allow to easily add references
> there from the main kernel Documentation, if needed in the future,
> without messing with local x non-local relative namespace.
> 
> Regards,
> Mauro

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel