Re: [PATCH v2 00/11] Fix some doc build warnings/errors and broken links

[Mauro Carvalho Chehab]

Em Thu, 10 May 2018 14:22:35 -0600
Jonathan Corbet  escreveu:

> On Wed,  9 May 2018 10:18:43 -0300
> Mauro Carvalho Chehab  wrote:
> 
> > Patches 1 to 5 on this series contain the patches that weren't yet
> > applied from the past patch series and touch only at Documentation.
> > There are two changes there:
> >   patch 2: fixed the description and added a c/c to cgroup maintainers;
> >   patch 4: rewritten according with Louis request, droping several hunks.  
> 
> Of these, I've applied 2, 4, and 6.  The networking and crypto folks like
> to apply their own documentation fixes; I assume they'll pick these up.

Hmm... I'm pretty sure I emailed about patch 4. Luis actually came with
a better solution: he partially removed the note, as it is outdated.
Better to revert it as otherwise it will rise conflicts at -next once
merged.

> 
> > Patch 6 rewrites scripts/documentation-file-ref-check on Perl,
> > adding an auto-fix feature.  
> 
> Applied this one.
> 
> > Patches 7 and 8 fix things that would cause troubles for the
> > automatic autocorrection tool.  
> 
> #7 is applied.  #8 doesn't apply, though; I'm not sure which tree you made
> it against?  In any case, I've stopped here for now.

Andrea commented about #8. You already applied an identical patch :-)

> > Patch 9 touches a lot of random places (including MAINTAINERS)
> > that contain broken links and can be auto-fixed. It could be
> > broken into one patch per touched file, but I think that is
> > overkill.   
> 
> Let's keep this one (and the ones that follow) aside.  I'm happy to apply
> them, but I think they are best applied as an end-of-merge-window thing.  I
> envision lots of conflicts, and I already have a pile of those to explain
> to Linus this time around.

Yeah, this patch touches on a lot of stuff. Better to handle it by the
end of a merge window.

I suspect you'll need to re-generate it by running this command again:

./scripts/documentation-file-ref-check --fix

But you should check the results, as false positives may arise.

If you prefer, I rebased the tree with the pending patches, placing
patch 9 at the end. This way, you'll likely avoid conflicts with
patches 10 and 11.

https://git.linuxtv.org/mchehab/experimental.git/log/?h=broken-links-v4

Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2 00/11] Fix some doc build warnings/errors and broken links

[Jonathan Corbet]

On Wed,  9 May 2018 10:18:43 -0300
Mauro Carvalho Chehab  wrote:

> Patches 1 to 5 on this series contain the patches that weren't yet
> applied from the past patch series and touch only at Documentation.
> There are two changes there:
>   patch 2: fixed the description and added a c/c to cgroup maintainers;
>   patch 4: rewritten according with Louis request, droping several hunks.

Of these, I've applied 2, 4, and 6.  The networking and crypto folks like
to apply their own documentation fixes; I assume they'll pick these up.

> Patch 6 rewrites scripts/documentation-file-ref-check on Perl,
> adding an auto-fix feature.

Applied this one.

> Patches 7 and 8 fix things that would cause troubles for the
> automatic autocorrection tool.

#7 is applied.  #8 doesn't apply, though; I'm not sure which tree you made
it against?  In any case, I've stopped here for now.

> Patch 9 touches a lot of random places (including MAINTAINERS)
> that contain broken links and can be auto-fixed. It could be
> broken into one patch per touched file, but I think that is
> overkill. 

Let's keep this one (and the ones that follow) aside.  I'm happy to apply
them, but I think they are best applied as an end-of-merge-window thing.  I
envision lots of conflicts, and I already have a pile of those to explain
to Linus this time around.

Sound good?

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 00/11] Fix some doc build warnings/errors and broken links

[Mauro Carvalho Chehab]

Hi Jon,

Patches 1 to 5 on this series contain the patches that weren't yet
applied from the past patch series and touch only at Documentation.
There are two changes there:
  patch 2: fixed the description and added a c/c to cgroup maintainers;
  patch 4: rewritten according with Louis request, droping several hunks.

Patch 6 rewrites scripts/documentation-file-ref-check on Perl,
adding an auto-fix feature.

Before doing that, I made a shell script version, but there are
several false positives there that would require some regex
parsing to get rid. Also, performance was problematic: even
on an i7core with SSD M.2 disk, it was taking more than a minute
just to identify the errors. The perl version makes it in less
than a second and gives more reliable results.

It should be noticed that, as any other auto-fix tool, the
resuls of the fix should be validated.

The next 5 patches contain several fixes based on its results.

Patches 7 and 8 fix things that would cause troubles for the
automatic autocorrection tool.

Patch 9 touches a lot of random places (including MAINTAINERS)
that contain broken links and can be auto-fixed. It could be
broken into one patch per touched file, but I think that is
overkill. 

Patch 10 fixes the removal of nmi_watchdog.txt.

Patch 11 do some manual fixes on most of the places where
the automatic fix tool found multiple hints.

Ah, I noticed also several broken links on media. Those
were fixed on 3 separate patches, submitted to linux-media.
I intend to apply them via my own tree.

Regards,
Mauro


Mauro Carvalho Chehab (11):
  docs: can.rst: fix a footnote reference
  docs: admin-guide: add cgroup-v2 documentation
  docs: crypto_engine.rst: Fix two parse warnings
  docs: dell_rbu.txt: fix location of request_firmware
  docs: uio-howto.rst: use a code block to solve a warning
  scripts/documentation-file-ref-check: rewrite it in perl with auto-fix
mode
  docs: ranoops.rst: fix location of ramoops.txt
  docs: refcount-vs-atomic.rst: prefix url with https
  docs: Fix some broken references
  arch/*: Kconfig: fix documentation for NMI watchdog
  docs: fix broken references with multiple hints

 Documentation/00-INDEX|   2 -
 Documentation/ABI/obsolete/sysfs-gpio |   2 +-
 .../cgroup-v2.rst}|   0
 Documentation/admin-guide/index.rst   |   1 +
 .../admin-guide/kernel-parameters.txt |   4 +-
 Documentation/admin-guide/ramoops.rst |   2 +-
 Documentation/core-api/refcount-vs-atomic.rst |   2 +-
 Documentation/crypto/crypto_engine.rst|   8 +-
 Documentation/dell_rbu.txt|   4 +-
 .../bindings/display/bridge/tda998x.txt   |   2 +-
 .../bindings/input/rotary-encoder.txt |   2 +-
 Documentation/driver-api/gpio/consumer.rst|   2 +-
 Documentation/driver-api/uio-howto.rst|   3 +-
 Documentation/kprobes.txt |   4 +-
 Documentation/networking/can.rst  |   4 +-
 Documentation/trace/coresight.txt |   2 +-
 Documentation/trace/events.rst|   4 +-
 Documentation/trace/ftrace-uses.rst   |   2 +-
 Documentation/trace/histogram.txt |   2 +-
 Documentation/trace/intel_th.rst  |   2 +-
 Documentation/trace/tracepoint-analysis.rst   |   8 +-
 Documentation/translations/ja_JP/howto.rst|   4 +-
 .../translations/zh_CN/SubmittingDrivers  |   2 +-
 Documentation/translations/zh_CN/gpio.txt |   4 +-
 .../translations/zh_CN/magic-number.txt   |   4 +-
 .../zh_CN/video4linux/omap3isp.txt|   4 +-
 MAINTAINERS   |  22 +--
 arch/Kconfig  |   2 +-
 arch/arm/Kconfig  |   2 +-
 arch/arm/include/asm/cacheflush.h |   2 +-
 arch/arm64/include/asm/cacheflush.h   |   2 +-
 arch/microblaze/include/asm/cacheflush.h  |   2 +-
 arch/parisc/Kconfig   |   2 +-
 arch/sh/Kconfig   |   2 +-
 arch/sparc/Kconfig|   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/hid/usbhid/Kconfig|   2 +-
 drivers/input/Kconfig |   4 +-
 drivers/input/joystick/Kconfig