When :doc: is used, the .rst should be removed. Also, the patches
are relative to the current directory.
So, the right reference should be:
:doc:`/accounting/delay-accounting`
Fixes: fcb501704554 ("delayacct: Document task_delayacct sysctl")
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/admin-guide/sysctl/kernel.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst
index b2057173fe07..7f36cba3204b 100644
--- a/Documentation/admin-guide/sysctl/kernel.rst
+++ b/Documentation/admin-guide/sysctl/kernel.rst
@@ -1097,7 +1097,7 @@ task_delayacct
===============
Enables/disables task delay accounting (see
-:doc:`accounting/delay-accounting.rst`). Enabling this feature incurs
+:doc:`/accounting/delay-accounting`). Enabling this feature incurs
a small amount of overhead in the scheduler but is useful for debugging
and performance tuning. It is required by some tools such as iotop.
--
2.31.1
Em Wed, 2 Jun 2021 18:38:29 +0200
Peter Zijlstra <[email protected]> escreveu:
> On Wed, Jun 02, 2021 at 05:43:13PM +0200, Mauro Carvalho Chehab wrote:
> > When :doc: is used, the .rst should be removed. Also, the patches
> > are relative to the current directory.
> >
> > So, the right reference should be:
> >
> > :doc:`/accounting/delay-accounting`
> >
> > Fixes: fcb501704554 ("delayacct: Document task_delayacct sysctl")
> > Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> > ---
> > Documentation/admin-guide/sysctl/kernel.rst | 2 +-
> > 1 file changed, 1 insertion(+), 1 deletion(-)
> >
> > diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst
> > index b2057173fe07..7f36cba3204b 100644
> > --- a/Documentation/admin-guide/sysctl/kernel.rst
> > +++ b/Documentation/admin-guide/sysctl/kernel.rst
> > @@ -1097,7 +1097,7 @@ task_delayacct
> > ===============
> >
> > 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.
> Can we please not do crap like this.
See, this is not the only place on this document using :doc:``. It is just
the one using it wrong:
$ git grep :doc: Documentation/admin-guide/sysctl/kernel.rst
Documentation/admin-guide/sysctl/kernel.rst:For general info and legal blurb, please look in :doc:`index`.
Documentation/admin-guide/sysctl/kernel.rst:See :doc:`/power/video`. This allows the video resume mode to be set,
Documentation/admin-guide/sysctl/kernel.rst::doc:`/x86/boot` for additional information.
Documentation/admin-guide/sysctl/kernel.rst::doc:`/x86/boot` for additional information.
Documentation/admin-guide/sysctl/kernel.rst:See :doc:`/driver-api/firmware/fallback-mechanisms`.
Documentation/admin-guide/sysctl/kernel.rst:See :doc:`/trace/ftrace`.
Documentation/admin-guide/sysctl/kernel.rst:See :doc:`/admin-guide/lockup-watchdogs` for more information.
Documentation/admin-guide/sysctl/kernel.rst:to the guest kernel command line (see :doc:`/admin-guide/kernel-parameters`).
Documentation/admin-guide/sysctl/kernel.rst:See :doc:`/admin-guide/initrd`.
Documentation/admin-guide/sysctl/kernel.rst::doc:`accounting/delay-accounting.rst`). Enabling this feature incurs
Documentation/admin-guide/sysctl/kernel.rst:See :doc:`/userspace-api/seccomp_filter`.
Documentation/admin-guide/sysctl/kernel.rst:See :doc:`/admin-guide/sysrq`.
Documentation/admin-guide/sysctl/kernel.rst:See :doc:`/admin-guide/tainted-kernels` for more information.
Documentation/admin-guide/sysctl/kernel.rst: See :doc:`/admin-guide/kernel-parameters` for more details on that particular
Documentation/admin-guide/sysctl/kernel.rst:When set, disables tracing (see :doc:`/trace/ftrace`) when a
Documentation/admin-guide/sysctl/kernel.rst:See :doc:`/admin-guide/kernel-parameters` and
Documentation/admin-guide/sysctl/kernel.rst::doc:`/trace/boottime-trace`.
-
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.
Tests are needed, though, to be sure that automarkup.py won't miss
something, as the regex there might require tweaks to cover some
border cases.
Thanks,
Mauro
Mauro Carvalho Chehab <[email protected]> writes:
> 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...
Thanks,
jon
Em Wed, 2 Jun 2021 20:29:23 +0200
Peter Zijlstra <[email protected]> escreveu:
> > Peter Zijlstra <[email protected]> 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 <[email protected]> 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.
Then, I'll send a separate patch series after 5.14-rc1 in order to
address the stuff under linux-next.
Thanks,
Mauro
Em Wed, 2 Jun 2021 22:19:40 +0200
Mauro Carvalho Chehab <[email protected]> escreveu:
> Em Wed, 2 Jun 2021 20:29:23 +0200
> Peter Zijlstra <[email protected]> escreveu:
>
> > > Peter Zijlstra <[email protected]> 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 <[email protected]> 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 <[email protected]>
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
Em Wed, 02 Jun 2021 12:36:05 -0600
Jonathan Corbet <[email protected]> escreveu:
> Mauro Carvalho Chehab <[email protected]> writes:
>
> > 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...
Hmm...
This patch caused a regression:
<patch>
PATCH] media: admin-guide: avoid using ReSt :doc:`foo` markup
The :doc:`foo` tag is auto-generated via automarkup.py.
So, use the filename at the sources, instead of :doc:`foo`.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
diff --git a/Documentation/admin-guide/media/index.rst b/Documentation/admin-guide/media/index.rst
index 6e0d2bae7154..5dbf6d02096a 100644
--- a/Documentation/admin-guide/media/index.rst
+++ b/Documentation/admin-guide/media/index.rst
@@ -11,10 +11,10 @@ its supported drivers.
Please see:
-- :doc:`/userspace-api/media/index`
+- Documentation/userspace-api/media/index.rst
for the userspace APIs used on media devices.
-- :doc:`/driver-api/media/index`
+- Documentation/driver-api/media/index.rst
for driver development information and Kernel APIs used by
media devices;
</patch>
This is the diff for the HTML output:
<diff>
diff --git a/admin-guide/media/index.html b/admin-guide/media/index.html
index 94c0cdf51579..28c083b75896 100644
--- a/admin-guide/media/index.html
+++ b/admin-guide/media/index.html
@@ -339,12 +339,12 @@ its supported drivers.</p>
<p>Please see:</p>
<ul class="simple">
<li><dl class="simple">
-<dt><a class="reference internal" href="../../userspace-api/media/index.html"><span class="doc">Linux Media Infrastructure userspace API</span></a></dt><dd><p>for the userspace APIs used on media devices.</p>
+<dt>Documentation/userspace-api/media/index.rst</dt><dd><p>for the userspace APIs used on media devices.</p>
</dd>
</dl>
</li>
<li><dl class="simple">
-<dt><a class="reference internal" href="../../driver-api/media/index.html"><span class="doc">Media subsystem kernel internal API</span></a></dt><dd><p>for driver development information and Kernel APIs used by
+<dt>Documentation/driver-api/media/index.rst</dt><dd><p>for driver development information and Kernel APIs used by
media devices;</p>
</dd>
</dl>
</diff>
It sounds that automarkup.py ignored it. Maybe because it is inside
a list?
Thanks,
Mauro
Hi Mauro,
and sorry for the late reply
On 2021-06-03 09:56, Mauro Carvalho Chehab wrote:
> 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 <[email protected]>
>
> My personal preference would be to keep using it for translations.
Why is this your preference? I would prefer to have a consistent style
everywhere.
If ":doc:" is now discouraged, then do not use it. What am I missing?
--
Federico Vaga