From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by smtp.lore.kernel.org (Postfix) with ESMTP id 7730AC36010 for ; Mon, 7 Apr 2025 14:03:39 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 49A5C6B0011; Mon, 7 Apr 2025 10:03:38 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 44AAC6B0012; Mon, 7 Apr 2025 10:03:38 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 339616B0022; Mon, 7 Apr 2025 10:03:38 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0013.hostedemail.com [216.40.44.13]) by kanga.kvack.org (Postfix) with ESMTP id 13F486B0011 for ; Mon, 7 Apr 2025 10:03:38 -0400 (EDT) Received: from smtpin23.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay02.hostedemail.com (Postfix) with ESMTP id 6E54F120930 for ; Mon, 7 Apr 2025 14:03:38 +0000 (UTC) X-FDA: 83307415716.23.1E40375 Received: from bali.collaboradmins.com (bali.collaboradmins.com [148.251.105.195]) by imf06.hostedemail.com (Postfix) with ESMTP id 92A25180005 for ; Mon, 7 Apr 2025 14:03:36 +0000 (UTC) Authentication-Results: imf06.hostedemail.com; dkim=pass header.d=collabora.com header.s=mail header.b=XbK+zNlm; dmarc=pass (policy=none) header.from=collabora.com; spf=pass (imf06.hostedemail.com: domain of nfraprado@collabora.com designates 148.251.105.195 as permitted sender) smtp.mailfrom=nfraprado@collabora.com ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1744034616; a=rsa-sha256; cv=none; b=mE9fI0rkNeWPtLsHFg4MlqAWo2iafQKf15OIbuR6OHqwEv4/Q27qpxmBaIuYysOay23IPk FCTHL+7fAOGYmlMtUErH1YCREP8iRjQGKliOEXRZsVATRu2Fbqjc019/912SQlOlGgeKjG zS0KWh6CDPPYIQG/hnTzpzarT9LohaA= ARC-Authentication-Results: i=1; imf06.hostedemail.com; dkim=pass header.d=collabora.com header.s=mail header.b=XbK+zNlm; dmarc=pass (policy=none) header.from=collabora.com; spf=pass (imf06.hostedemail.com: domain of nfraprado@collabora.com designates 148.251.105.195 as permitted sender) smtp.mailfrom=nfraprado@collabora.com ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1744034616; h=from:from:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:dkim-signature; bh=vqPo4BJw+Ec/ACl21W0maFoVCJxW/RDcMRbTDnWNsJI=; b=mQw3bFD42GOxEUUwv8OeSZc2Ic7iAklYphWQM8riFBmvCIHXfWqtTjE/BxyN+x1BhOgSHA mUjbPOn5Bpp5W0fBvuzrvlk+jFMHi7lBpY26DTORKJZcBNGT8RbOcrmhH3FME5WEl7UyfA fmXAyBBKIia+lYxqbYUmDQXAZMmihn0= DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=collabora.com; s=mail; t=1744034614; bh=LwpFHqtTF6aiM+1soPf8ma0ZkEP2mzQ1iN1O5ga09M4=; h=Date:From:To:Cc:Subject:References:In-Reply-To:From; b=XbK+zNlmEYMyXgy9EE+nYDPMS6CNvfQvS4m8Ns622tsZ+iUYZZUmQVKBc+XlC+Ex0 LaVUBaVnuHyN4MmHQRM5lw75L9OtxOhDCkjuYODTe+qjTI/m5+AMTxT0Gka7jc0QE8 IifRhyjZZYK5QvnI+mMIhrnYhTnAo9KP5sABY5mQ6fcU6WPvsT9xj3IKWxPUaa7KsX WNf9C7FVgUYYMwv/V1hMAOJBiisS+blTU874Zclxv4aFp9RB6gJyAyCkEp32WSgf2b YGO6OexvWQ9aiFyaesw8sjta8FGk9hz0lRUCH2EruQhXMFQ6T/BIolXXN9TstLXeHQ P+ItjRt/WHB3Q== Received: from notapiano (unknown [70.107.117.78]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange ECDHE (prime256v1) server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) (Authenticated sender: nfraprado) by bali.collaboradmins.com (Postfix) with ESMTPSA id D60C917E02BE; Mon, 7 Apr 2025 16:03:28 +0200 (CEST) Date: Mon, 7 Apr 2025 10:03:26 -0400 From: =?utf-8?B?TsOtY29sYXMgRi4gUi4gQS4=?= Prado To: Akira Yokosawa Cc: James.Bottomley@hansenpartnership.com, akpm@linux-foundation.org, anton.ivanov@cambridgegreys.com, corbet@lwn.net, davem@davemloft.net, dmaengine@vger.kernel.org, ebiggers@kernel.org, edumazet@google.com, horms@kernel.org, jaegeuk@kernel.org, jarkko@kernel.org, jic23@kernel.org, johannes@sipsolutions.net, kernel@collabora.com, keyrings@vger.kernel.org, kuba@kernel.org, lars@metafoo.de, linux-doc@vger.kernel.org, linux-fscrypt@vger.kernel.org, linux-iio@vger.kernel.org, linux-integrity@vger.kernel.org, linux-kernel@vger.kernel.org, linux-media@vger.kernel.org, linux-mm@kvack.org, linux-sound@vger.kernel.org, linux-um@lists.infradead.org, maxime.chevallier@bootlin.com, mchehab@kernel.org, netdev@vger.kernel.org, pabeni@redhat.com, perex@perex.cz, richard@nod.at, tiwai@suse.com, tytso@mit.edu, vkoul@kernel.org, workflows@vger.kernel.org, zohar@linux.ibm.com Subject: Re: [PATCH] docs: Remove literal markup from Documentation/ paths Message-ID: <9bc7b77b-73a7-4d6d-9187-ac452f8cad23@notapiano> References: <20250404-doc-paths-unliteral-v1-1-74718785444e@collabora.com> <811c4103-08b1-4288-9a15-bd9795bc59f4@gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: <811c4103-08b1-4288-9a15-bd9795bc59f4@gmail.com> X-Rspamd-Server: rspam04 X-Rspamd-Queue-Id: 92A25180005 X-Stat-Signature: y3371878dgqhopdq1kjgdat7e76njasm X-Rspam-User: X-HE-Tag: 1744034616-228570 X-HE-Meta: U2FsdGVkX18nAdhlAlGmu1SsK+TU+0l5keBNdL7+gtZ2v0eWKDN8h4/NTvEdkJCtBage89vsBkFeE4w9KsLrS4Du7c7ncpHZmumqfq/ij4dlSoFddFBI9zArMIJZYCddI4ymfzaJfvS8rC4N9iU1zLmnLJIMN1ZsRH3mQw+loZj0ccgF6GaFB8Hpr1FzcxhbpN722nE/DMBuiVuWk6mB1FewIDax2K4yeyYO24g3PJuR4A5cSTIVJ21+efylyf4baLJYWzXRFzaPCLfYW93VjNWCDm3TPhvC0Kp6jgZImksn5ZVa4RE/FC4RbesSMMYreF264+t1W+VQ+KZs+YwdE2o2SOBh072SmiB2YO3ohjBAhRK3d5aAM+CCPLlH+ASJgJfu5M0udjlXqpgJrxS+DxaPt7zszmfAZROMxxwsVfNIedaZVcTmerSqqQKfAfERhOzq6Lca1buXaNdGOL8Pj4/Dwwsi9NaE3ju8COFMqsEm2raszIMLw2kByxVwhfKugzAtsTNOsbOOugXy+TdMExMG6BWv2/4cLNqi9Vsd+FfSJCaPTol+8MCoJRnOxdk1p6rEAZp5sWQmiudrRiDMqtQJTsAY/UAQ171/bJB5kTgaTYlxYTSXX5oKaj2h3v7BVS0jXOL9lA/Ju9+Q/5rpzC+awwXp4JPWy47i/hjqonZGAFON+uJezTT9Za5JJWUmIYAtbGnFJHXBdCI9MOMl8IDW0KKjSU3jZ85M9lAXVoPdCvNi8KrnPJiNbhW1oybiQJOKH8RwSx2BlMBNOqLav+I7tLH8vkxcqaE/hqIkxvBVii0SHeanevs/NWv+I5m4UD/UOlXEVXERI7uT+pcbAZYCLFBnVgde/Lpt33iqYKwqKhNRzi81B6G+R9b+pyFxPxEKKjUyANqm0/ioGGgHXBjfGB3mlgZ3peOCLPwLSq3L1pM+YkFub4c1/mWK8zvcXMP1wjJ4hvtCHux3SHR QjA== X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: List-Subscribe: List-Unsubscribe: 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 > > --- [..] > > > > 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@vger.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 > > ========================== >