Re: [PATCH 07/12] docs: accounting: update delay-accounting.rst reference
From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Date: 2021-06-03 07:56:42
Also in:
lkml
Em Wed, 2 Jun 2021 22:19:40 +0200 Mauro Carvalho Chehab [off-list ref] escreveu:
Em Wed, 2 Jun 2021 20:29:23 +0200 Peter Zijlstra [off-list ref] escreveu:quoted
quoted
Peter Zijlstra [off-list ref] escreveu:quoted
On Wed, Jun 02, 2021 at 05:43:13PM +0200, Mauro Carvalho Chehab wrote:quoted
quoted
quoted
Enables/disables task delay accounting (see -:doc:`accounting/delay-accounting.rst`). Enabling this feature incurs +:doc:`/accounting/delay-accounting`). Enabling this feature incursThis 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 [off-list ref] escreveu:quoted
quoted
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 [off-list ref] 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