Re: [PATCH 07/12] docs: accounting: update delay-accounting.rst reference

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Wed, 2 Jun 2021 22:19:40 +0200
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> escreveu:

> Em Wed, 2 Jun 2021 20:29:23 +0200
> Peter Zijlstra <peterz@infradead.org> escreveu:
> 
> > > Peter Zijlstra <peterz@infradead.org> escreveu:
> > >     
> > > > On Wed, Jun 02, 2021 at 05:43:13PM +0200, Mauro Carvalho Chehab wrote:    
> >   
> > > > >  Enables/disables task delay accounting (see
> > > > > -:doc:`accounting/delay-accounting.rst`). Enabling this feature incurs
> > > > > +:doc:`/accounting/delay-accounting`). Enabling this feature incurs      
> > > > 
> > > > This breaks any chance of using 'goto file' like features in text
> > > > editors :/     
> > > 
> > > This is a feature of your favorite text editor. Not all have it.    
> > 
> > Afaict both vim (gf) and emacs (M-x ffap) can do this. That covers about
> > 99% of all sane editors no? :-)  
> 
> Heh, not quite ;-) Here, I use nano(/pico), from the old times where 
> (al)pine was my emailer. I can live with vim, but I prefer an editor
> that starts in editing mode.
> 
> I tried to use emacs a few times, but my fingers are too much into
> pico/nano control keys, so it was ending by making me typing a lot
> slower. Besides that, nano works well on 99% of my daily needs. 
> 
> When I need more fancy, like regex substitutions, changing/moving
> big code blocks, editing multiple files at the same time, etc, 
> then I just use a GUI editor (currently kate, but seeking for
> a good replacement, as some changes during F33 times - still 
> present on F34 - caused some regressions).
> 
> Em Wed, 02 Jun 2021 12:36:05 -0600
> Jonathan Corbet <corbet@lwn.net> escreveu:
> 
> > > That's said, automarkup.py has a rule to convert Documentation/<foo>.rst
> > > into :doc:`<foo>`. So, an alternative approach would be to convert
> > > treewide all :doc:`<foo>` into Documentation/<foo>.rst and add something 
> > > at checkpatch.pl to recommend to avoid :doc: notation.    
> > 
> > That seems like the right approach to me.  We have the automarkup
> > capability, we might as well make use of it...  
> 
> Ok, I'll prepare a separate patch series addressing it. 
> 
> -
> 
> Jon,
> 
> With regards to the :doc: -> Documentation/ conversion, I guess I'll
> do it on an independent patch series against your docs-next tree.

A pure replace of two patterns:

	:doc:\`(/[^\`]+)\`
	:doc:\`([^\`\<]+)\`

Produced this result:

 Documentation/PCI/endpoint/pci-endpoint-cfs.rst                             |  2 +-
 Documentation/PCI/pci.rst                                                   |  6 +++---
 Documentation/admin-guide/hw-vuln/special-register-buffer-data-sampling.rst |  2 +-
 Documentation/admin-guide/media/bt8xx.rst                                   |  8 ++++----
 Documentation/admin-guide/media/bttv.rst                                    | 14 +++++++-------
 Documentation/admin-guide/media/index.rst                                   |  4 ++--
 Documentation/admin-guide/media/saa7134.rst                                 |  2 +-
 Documentation/admin-guide/pm/intel_idle.rst                                 | 10 +++++-----
 Documentation/admin-guide/pm/intel_pstate.rst                               |  4 ++--
 Documentation/admin-guide/sysctl/abi.rst                                    |  2 +-
 Documentation/admin-guide/sysctl/kernel.rst                                 | 32 ++++++++++++++++----------------
 Documentation/block/biodoc.rst                                              |  2 +-
 Documentation/bpf/bpf_lsm.rst                                               |  4 ++--
 Documentation/core-api/bus-virt-phys-mapping.rst                            |  2 +-
 Documentation/core-api/dma-api.rst                                          |  4 ++--
 Documentation/core-api/dma-isa-lpc.rst                                      |  2 +-
 Documentation/core-api/index.rst                                            |  4 ++--
 Documentation/dev-tools/kunit/api/index.rst                                 |  2 +-
 Documentation/dev-tools/kunit/faq.rst                                       |  2 +-
 Documentation/dev-tools/kunit/index.rst                                     | 14 +++++++-------
 Documentation/dev-tools/kunit/start.rst                                     |  6 +++---
 Documentation/dev-tools/kunit/tips.rst                                      |  4 ++--
 Documentation/dev-tools/kunit/usage.rst                                     |  6 +++---
 Documentation/dev-tools/testing-overview.rst                                |  4 ++--
 Documentation/devicetree/bindings/submitting-patches.rst                    |  2 +-
 Documentation/doc-guide/contributing.rst                                    |  8 ++++----
 Documentation/driver-api/gpio/using-gpio.rst                                |  4 ++--
 Documentation/driver-api/ioctl.rst                                          |  2 +-
 Documentation/driver-api/media/drivers/bttv-devel.rst                       |  2 +-
 Documentation/driver-api/media/index.rst                                    |  4 ++--
 Documentation/driver-api/pm/devices.rst                                     |  2 +-
 Documentation/driver-api/surface_aggregator/clients/index.rst               |  2 +-
 Documentation/driver-api/surface_aggregator/internal.rst                    |  6 +++---
 Documentation/driver-api/surface_aggregator/overview.rst                    |  4 ++--
 Documentation/driver-api/usb/dma.rst                                        |  6 +++---
 Documentation/firmware-guide/acpi/dsd/data-node-references.rst              |  2 +-
 Documentation/firmware-guide/acpi/dsd/graph.rst                             |  2 +-
 Documentation/firmware-guide/acpi/enumeration.rst                           |  2 +-
 Documentation/hwmon/adm1177.rst                                             |  2 +-
 Documentation/i2c/instantiating-devices.rst                                 |  2 +-
 Documentation/i2c/old-module-parameters.rst                                 |  2 +-
 Documentation/i2c/smbus-protocol.rst                                        |  2 +-
 Documentation/kernel-hacking/hacking.rst                                    |  4 ++--
 Documentation/networking/devlink/devlink-region.rst                         |  2 +-
 Documentation/networking/devlink/devlink-trap.rst                           |  4 ++--
 Documentation/process/submitting-patches.rst                                | 12 ++++++------
 Documentation/security/landlock.rst                                         |  2 +-
 Documentation/trace/coresight/coresight.rst                                 |  6 +++---
 Documentation/trace/ftrace.rst                                              |  2 +-
 Documentation/translations/it_IT/core-api/symbol-namespaces.rst             |  2 +-
 Documentation/translations/it_IT/kernel-hacking/hacking.rst                 |  4 ++--
 Documentation/translations/it_IT/process/email-clients.rst                  |  2 +-
 Documentation/translations/it_IT/process/management-style.rst               |  2 +-
 Documentation/translations/it_IT/process/submitting-patches.rst             | 14 +++++++-------
 Documentation/translations/it_IT/riscv/patch-acceptance.rst                 |  2 +-
 Documentation/translations/zh_CN/admin-guide/bug-bisect.rst                 |  2 +-
 Documentation/translations/zh_CN/admin-guide/bug-hunting.rst                |  2 +-
 Documentation/translations/zh_CN/admin-guide/index.rst                      |  2 +-
 Documentation/translations/zh_CN/admin-guide/init.rst                       |  2 +-
 Documentation/translations/zh_CN/admin-guide/security-bugs.rst              |  2 +-
 Documentation/translations/zh_CN/admin-guide/tainted-kernels.rst            |  2 +-
 Documentation/translations/zh_CN/core-api/index.rst                         |  6 +++---
 Documentation/translations/zh_CN/core-api/irq/concepts.rst                  |  2 +-
 Documentation/translations/zh_CN/core-api/irq/index.rst                     |  2 +-
 Documentation/translations/zh_CN/core-api/irq/irq-affinity.rst              |  2 +-
 Documentation/translations/zh_CN/core-api/irq/irq-domain.rst                |  2 +-
 Documentation/translations/zh_CN/core-api/irq/irqflags-tracing.rst          |  2 +-
 Documentation/translations/zh_CN/cpu-freq/core.rst                          |  2 +-
 Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst                   |  2 +-
 Documentation/translations/zh_CN/cpu-freq/cpufreq-stats.rst                 |  2 +-
 Documentation/translations/zh_CN/cpu-freq/index.rst                         |  2 +-
 Documentation/translations/zh_CN/filesystems/debugfs.rst                    |  2 +-
 Documentation/translations/zh_CN/iio/ep93xx_adc.rst                         |  2 +-
 Documentation/translations/zh_CN/iio/iio_configfs.rst                       |  2 +-
 Documentation/translations/zh_CN/iio/index.rst                              |  2 +-
 Documentation/translations/zh_CN/mips/booting.rst                           |  2 +-
 Documentation/translations/zh_CN/mips/features.rst                          |  2 +-
 Documentation/translations/zh_CN/mips/index.rst                             |  2 +-
 Documentation/translations/zh_CN/mips/ingenic-tcu.rst                       |  2 +-
 Documentation/translations/zh_CN/openrisc/index.rst                         |  2 +-
 Documentation/translations/zh_CN/openrisc/openrisc_port.rst                 |  2 +-
 Documentation/translations/zh_CN/openrisc/todo.rst                          |  2 +-
 Documentation/translations/zh_CN/riscv/boot-image-header.rst                |  2 +-
 Documentation/translations/zh_CN/riscv/index.rst                            |  2 +-
 Documentation/translations/zh_CN/riscv/patch-acceptance.rst                 |  2 +-
 Documentation/translations/zh_CN/riscv/pmu.rst                              |  2 +-
 Documentation/translations/zh_CN/sound/hd-audio/index.rst                   |  2 +-
 Documentation/translations/zh_CN/sound/index.rst                            |  2 +-
 Documentation/userspace-api/landlock.rst                                    |  8 ++++----
 Documentation/userspace-api/media/glossary.rst                              |  2 +-
 Documentation/userspace-api/media/index.rst                                 |  4 ++--
 Documentation/virt/kvm/s390-pv-boot.rst                                     |  2 +-
 Documentation/x86/boot.rst                                                  |  4 ++--
 Documentation/x86/mtrr.rst                                                  |  2 +-
 94 files changed, 174 insertions(+), 174 deletions(-)

Some manual work is needed, as a couple of replacements occurred inside
tables. I also need to check if automarkup.py got everything, including
the ones inside tables.

I'm in doubt with regards to translations. There, the tag is used
to point to the original translation, like on
Documentation/translations/it_IT/core-api/symbol-namespaces.rst:

	:Original: :doc:`../../../core-api/symbol-namespaces`
	:Translator: Federico Vaga <federico.vaga@vaga.pv.it>

My personal preference would be to keep using it for translations.

There are, however, two special cases:

1. Named cross-references with a documentation path:

	:doc:`Non-Transparent Bridge <../../driver-api/ntb>`

   As the end result (in html) would be something like:

	<a href="../../driver-api/ntb.html>Non-Transparent Bridge</a>

   We might just ignore the name and convert it into:

	Documentation/driver-api/ntb.rst

   but this sounds a bad idea on my eyes, as some context can be missed.

   So, I would keep using :doc: on such cases.

2. Named cross-references without a path:

	:doc: AMDGPU RAS Reboot Behavior for Unrecoverable Errors

   This actually guides to a kernel-doc markup inside a C file:

	drivers/gpu/drm/amd/amdgpu/amdgpu_ras.c: * DOC: AMDGPU RAS Reboot Behavior for Unrecoverable Errors

   So, those can't be converted.

The net result is that a warning at checkpatch.pl about the usage of 
:doc: would need to exclude those special cases.

Thanks,
Mauro