[<prev] [next>] [<thread-prev] [day] [month] [year] [list]
Message-ID: <9bc7b77b-73a7-4d6d-9187-ac452f8cad23@notapiano>
Date: Mon, 7 Apr 2025 10:03:26 -0400
From: Nícolas F. R. A. Prado <nfraprado@...labora.com>
To: Akira Yokosawa <akiyks@...il.com>
Cc: James.Bottomley@...senpartnership.com, akpm@...ux-foundation.org,
anton.ivanov@...bridgegreys.com, corbet@....net,
davem@...emloft.net, dmaengine@...r.kernel.org, ebiggers@...nel.org,
edumazet@...gle.com, horms@...nel.org, jaegeuk@...nel.org,
jarkko@...nel.org, jic23@...nel.org, johannes@...solutions.net,
kernel@...labora.com, keyrings@...r.kernel.org, kuba@...nel.org,
lars@...afoo.de, linux-doc@...r.kernel.org,
linux-fscrypt@...r.kernel.org, linux-iio@...r.kernel.org,
linux-integrity@...r.kernel.org, linux-kernel@...r.kernel.org,
linux-media@...r.kernel.org, linux-mm@...ck.org,
linux-sound@...r.kernel.org, linux-um@...ts.infradead.org,
maxime.chevallier@...tlin.com, mchehab@...nel.org,
netdev@...r.kernel.org, pabeni@...hat.com, perex@...ex.cz,
richard@....at, tiwai@...e.com, tytso@....edu, vkoul@...nel.org,
workflows@...r.kernel.org, zohar@...ux.ibm.com
Subject: Re: [PATCH] docs: Remove literal markup from Documentation/ paths
On Sat, Apr 05, 2025 at 10:17:16AM +0900, Akira Yokosawa wrote:
> Hi,
>
> Nícolas F. R. A. Prado wrote:
> > Given that the automarkup Sphinx plugin cross-references
> > "Documentation/*.rst" strings in the text to the corresponding
> > documents, surrounding those strings with the literal markup (``) not
> > only adds unnecessary markup in the source files, but actually prevents
> > the automatic cross-referencing to happen (as it doesn't happen in
> > literal blocks).
> >
> > Remove all the occurrences of the literal markup in
> > "Documentation/*.rst" paths, except when the actual source file is being
> > referred. Also change the surrounding text when needed so it reads well
> > both in the source and the web page (eg. 'see file Doc...' -> 'see
> > Doc...').
> >
> > Signed-off-by: Nícolas F. R. A. Prado <nfraprado@...labora.com>
> > ---
[..]
> >
> > 2) All new ``Kconfig`` options have help text.
> >
> > @@ -47,7 +48,7 @@ Provide documentation
> > 2) All new ``/proc`` entries are documented under ``Documentation/``
> >
> > 3) All new kernel boot parameters are documented in
> > - ``Documentation/admin-guide/kernel-parameters.rst``.
> > + Documentation/admin-guide/kernel-parameters.rst.
>
> Hmm, this item is asking "Have you documented the new params in that
> particular file?", so I don't think this change should be made.
Right, that makes sense. I'll drop this and the below change for v2.
Thanks,
Nícolas
>
> >
> > 4) All new module parameters are documented with ``MODULE_PARM_DESC()``
> >
> > @@ -58,7 +59,7 @@ Provide documentation
> > linux-api@...r.kernel.org.
> >
> > 6) If any ioctl's are added by the patch, then also update
> > - ``Documentation/userspace-api/ioctl/ioctl-number.rst``.
> > + Documentation/userspace-api/ioctl/ioctl-number.rst.
>
> Ditto.
>
> Thanks, Akira
>
> >
> > Check your code with tools
> > ==========================
>
Powered by blists - more mailing lists