linux-kernel - Re: [PATCH v2] Documentation/process: add soc maintainer handbook

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20230530-enviable-poise-183119e695bf@wendy>
Date:   Tue, 30 May 2023 14:12:07 +0100
From:   Conor Dooley <conor.dooley@...rochip.com>
To:     Jonathan Corbet <corbet@....net>
CC:     <soc@...nel.org>, <conor@...nel.org>, <devicetree@...r.kernel.org>,
        <krzysztof.kozlowski+dt@...aro.org>,
        <linux-arm-kernel@...ts.infradead.org>,
        <linux-doc@...r.kernel.org>, <linux-kernel@...r.kernel.org>,
        <linux-riscv@...ts.infradead.org>, <olof@...om.net>,
        <palmer@...belt.com>, <robh+dt@...nel.org>, <arnd@...db.de>
Subject: Re: [PATCH v2] Documentation/process: add soc maintainer handbook

On Tue, May 30, 2023 at 07:02:26AM -0600, Jonathan Corbet wrote:
> Conor Dooley <conor.dooley@...rochip.com> writes:

> > diff --git a/Documentation/devicetree/bindings/ABI.rst b/Documentation/devicetree/bindings/ABI.rst
> > index a885713cf184..93ec82f78ae5 100644
> > --- a/Documentation/devicetree/bindings/ABI.rst
> > +++ b/Documentation/devicetree/bindings/ABI.rst
> > @@ -1,5 +1,7 @@
> >  .. SPDX-License-Identifier: GPL-2.0
> >  
> > +.. _devicetree-abi:
> 
> Somehow we've developed this habit of putting labels at the top of each
> file; I really think that they just add clutter and are best left out.
> Without the label, this reference:
> 
> > +Perhaps one of the most important things to highlight is that dt-bindings
> > +document the ABI between the devicetree and the kernel. Please see
> > +:ref:`devicetree-abi` more information on the ABI.
> 
> ...can just be written as "Please see
> Documentation/devicetree/bindings/ABI.rst".  The cross-reference link
> will be generated as expected, and readers of the plain-text docs don't
> have to go grepping to find the reference.

Sure. As someone who does read these things in their editor that sounds
preferable to me. I didn't know that I could do that, as the whole
"building the docs" thing is new to me ;)
I'll wait a bit before resubmitting for obvious reasons.

Cheers,
Conor.

Download attachment "signature.asc" of type "application/pgp-signature" (229 bytes)