linux-kernel - Re: [PATCH] docs: Remove literal markup from Documentation/ paths

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: <811c4103-08b1-4288-9a15-bd9795bc59f4@gmail.com>
Date: Sat, 5 Apr 2025 10:17:16 +0900
From: Akira Yokosawa <akiyks@...il.com>
To: nfraprado@...labora.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, Akira Yokosawa <akiyks@...il.com>
Subject: Re: [PATCH] docs: Remove literal markup from Documentation/ paths

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>
> ---
[...]

>  Documentation/process/submit-checklist.rst                | 7 ++++---

I have updated ja_JP translation of this recently.

> diff --git a/Documentation/process/submit-checklist.rst b/Documentation/process/submit-checklist.rst
> index beb7f94279fdb6a1d9b4aa86b2bea031f140732b..3ae31c5af2cb5c374658c1fb7125e70bf36e911c 100644
> --- a/Documentation/process/submit-checklist.rst
> +++ b/Documentation/process/submit-checklist.rst
> @@ -30,7 +30,8 @@ Review Kconfig changes
>  
>  1) Any new or modified ``CONFIG`` options do not muck up the config menu and
>     default to off unless they meet the exception criteria documented in
> -   ``Documentation/kbuild/kconfig-language.rst`` Menu attributes: default value.
> +   Documentation/kbuild/kconfig-language.rst, under "Menu attributes", "default
> +   value".

I have made the same change in the translation, but failed to submit a patch...

>  
>  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.

>  
>  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
>  ==========================