linux-doc.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Jonathan Corbet <corbet@lwn.net>
Cc: Peter Zijlstra <peterz@infradead.org>,
	Linux Doc Mailing List <linux-doc@vger.kernel.org>,
	"Guilherme G. Piccoli" <gpiccoli@canonical.com>,
	Andrew Morton <akpm@linux-foundation.org>,
	Daniel Borkmann <daniel@iogearbox.net>,
	Kees Cook <keescook@chromium.org>, Lepton Wu <ytht.net@gmail.com>,
	Mel Gorman <mgorman@suse.de>, Qais Yousef <qais.yousef@arm.com>,
	Randy Dunlap <rdunlap@infradead.org>,
	Rasmus Villemoes <linux@rasmusvillemoes.dk>,
	Stephen Kitt <steve@sk2.org>, Wang Qing <wangqing@vivo.com>,
	linux-kernel@vger.kernel.org, federico.vaga@vaga.pv.it
Subject: Re: [PATCH 07/12] docs: accounting: update delay-accounting.rst reference
Date: Thu, 3 Jun 2021 09:56:32 +0200	[thread overview]
Message-ID: <20210603095632.35ab9fee@coco.lan> (raw)
In-Reply-To: <20210602221940.7e0a6135@coco.lan>

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

  parent reply	other threads:[~2021-06-03  7:56 UTC|newest]

Thread overview: 36+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-06-02 15:43 [PATCH 00/12] Fix broken docs references at next-20210602 Mauro Carvalho Chehab
2021-06-02 15:43 ` [PATCH 01/12] dt-bindings: power: supply: cpcap-battery: update cpcap-battery.yaml reference Mauro Carvalho Chehab
2021-06-03  1:54   ` Rob Herring
2021-06-02 15:43 ` [PATCH 02/12] dt-bindings: power: supply: cpcap-charger: update cpcap-charger.yaml reference Mauro Carvalho Chehab
2021-06-03  1:54   ` Rob Herring
2021-06-02 15:43 ` [PATCH 03/12] dt-bindings: soc: ti: update sci-pm-domain.yaml references Mauro Carvalho Chehab
2021-06-02 21:03   ` Rob Herring
2021-06-03 20:08   ` Wolfram Sang
2021-06-02 15:43 ` [PATCH 04/12] dt-bindings: clock: update ti,sci-clk.yaml references Mauro Carvalho Chehab
2021-06-02 21:04   ` Rob Herring
2021-06-03 20:09   ` Wolfram Sang
2021-06-02 15:43 ` [PATCH 05/12] dt-bindings: reset: update ti,sci-reset.yaml references Mauro Carvalho Chehab
2021-06-02 21:04   ` Rob Herring
2021-06-02 15:43 ` [PATCH 06/12] dt-bindings: iio: io-channel-mux.yaml: fix a typo Mauro Carvalho Chehab
2021-06-02 21:04   ` Rob Herring
2021-06-02 15:43 ` [PATCH 07/12] docs: accounting: update delay-accounting.rst reference Mauro Carvalho Chehab
2021-06-02 16:38   ` Peter Zijlstra
2021-06-02 18:01     ` Mauro Carvalho Chehab
2021-06-02 18:29       ` Peter Zijlstra
2021-06-02 18:36       ` Jonathan Corbet
2021-06-02 20:19         ` Mauro Carvalho Chehab
2021-06-03  7:20           ` Peter Zijlstra
2021-06-03  7:56           ` Mauro Carvalho Chehab [this message]
2021-07-04 13:52             ` Federico Vaga
2021-06-03 11:35         ` Mauro Carvalho Chehab
2021-06-02 15:43 ` [PATCH 08/12] MAINTAINERS: update faraday,ftrtc010.yaml reference Mauro Carvalho Chehab
2021-06-06 22:50   ` Linus Walleij
2021-06-07  8:14   ` Alexandre Belloni
2021-06-02 15:43 ` [PATCH 09/12] MAINTAINERS: update marvell,armada-3700-utmi-phy.yaml reference Mauro Carvalho Chehab
2021-06-03  6:11   ` Vinod Koul
2021-06-02 15:43 ` [PATCH 10/12] MAINTAINERS: update ti,omap-gpio.yaml reference Mauro Carvalho Chehab
2021-06-07 14:15   ` Bartosz Golaszewski
2021-06-02 15:43 ` [PATCH 11/12] MAINTAINERS: update ti,sci.yaml reference Mauro Carvalho Chehab
2021-06-02 15:43 ` [PATCH 12/12] MAINTAINERS: update nxp,imx8-jpeg.yaml reference Mauro Carvalho Chehab
2021-06-03  8:18   ` [EXT] " Mirela Rabulea
2021-06-03 20:00 ` [PATCH 00/12] Fix broken docs references at next-20210602 Rob Herring

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20210603095632.35ab9fee@coco.lan \
    --to=mchehab+huawei@kernel.org \
    --cc=akpm@linux-foundation.org \
    --cc=corbet@lwn.net \
    --cc=daniel@iogearbox.net \
    --cc=federico.vaga@vaga.pv.it \
    --cc=gpiccoli@canonical.com \
    --cc=keescook@chromium.org \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux@rasmusvillemoes.dk \
    --cc=mgorman@suse.de \
    --cc=peterz@infradead.org \
    --cc=qais.yousef@arm.com \
    --cc=rdunlap@infradead.org \
    --cc=steve@sk2.org \
    --cc=wangqing@vivo.com \
    --cc=ytht.net@gmail.com \
    --subject='Re: [PATCH 07/12] docs: accounting: update delay-accounting.rst reference' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).