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

Mauro Carvalho Chehab
2018-05-09T18:20:45Z

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:

${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