Received-SPF: pass (google.com: domain of linux-kernel+bounces-112537-linux.lists.archive=gmail.com@vger.kernel.org designates 147.75.48.161 as permitted sender) client-ip=147.75.48.161;
Date: Sat, 23 Mar 2024 17:57:45 -0700
From: Dan Williams <dan.j.williams@intel.com>
To: Matthew Wilcox <willy@infradead.org>, Dan Williams
	<dan.j.williams@intel.com>
CC: Peter Zijlstra <peterz@infradead.org>, <torvalds@linux-foundation.org>,
	Bjorn Helgaas <bhelgaas@google.com>, Ira Weiny <ira.weiny@intel.com>,
	Jonathan Cameron <jonathan.cameron@huawei.com>, Jesse Brandeburg
	<jesse.brandeburg@intel.com>, Ilpo =?iso-8859-1?Q?J=E4rvinen?=
	<ilpo.jarvinen@linux.intel.com>, Lukas Wunner <lukas.wunner@intel.com>,
	Jonathan Corbet <corbet@lwn.net>, <linux-pci@vger.kernel.org>,
	<linux-kernel@vger.kernel.org>, <gregkh@linuxfoundation.org>,
	<linux-doc@vger.kernel.org>
Subject: Re: [PATCH] cleanup: Add usage and style documentation
Message-ID: <65ff7a88e93fb_2690d29429@dwillia2-mobl3.amr.corp.intel.com.notmuch>
References: <171097196970.1011049.9726486429680041876.stgit@dwillia2-xfh.jf.intel.com>
 <20240322090630.GA40102@noisy.programming.kicks-ass.net>
 <65fdd7ae82934_4a98a29429@dwillia2-mobl3.amr.corp.intel.com.notmuch>
 <Zf8_RYHW7QmCzl2-@casper.infradead.org>
Content-Type: text/plain; charset="us-ascii"
Content-Disposition: inline
In-Reply-To: <Zf8_RYHW7QmCzl2-@casper.infradead.org>
Precedence: bulk
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: =?us-ascii?Q?AgefWEyseVXz2vpwu40bJvDOgNsL/F9bb6iGohG9B7eH1yROCSCkJ3IiFLz6?=
 =?us-ascii?Q?cNe27ftssJz9Yu9Kt1zNQyPVwcbp/H35ziFLfphv4eQs1DMZA2XC2J79DtAO?=
 =?us-ascii?Q?QgDk0NRyWSh6PYY3pQASYi6xw/Hpm0Tu0hAzf7tG/cEHkmdFqM1VOgXcXO0q?=
 =?us-ascii?Q?HFl+lgVLXx6Pp6x6b+PPcG4KtCNz1fRogoZvxzKiuokXKaterT1A7cGP0qpI?=
 =?us-ascii?Q?QqSx0GPhEmT9qMIAoNnATCX46uFJQ7+MbFd4T7A922bcREk5wFo74ZGIueNj?=
 =?us-ascii?Q?2JcEu4x2sCH14y8rb2fgoago5t+4D3+EtC85IbriuPILs0SeEqXZ0hN9OS0E?=
 =?us-ascii?Q?kLcq6J3yNQvJjZ3lI4HMRn9IikToO8Ju/4yYK5Rwb0L789ghridOeUDdhnqn?=
 =?us-ascii?Q?8o0z4j+TI7yuJpMSgsbiyeB0M3xfAYTFVx4jKrdaMANryUZdPb4MIjmVNd2w?=
 =?us-ascii?Q?W67itzN8wxu3lDLfWhLkKDsVzE4gFmnRsaAraowd/SU0dXbyK/kXr5+cYQ5a?=
 =?us-ascii?Q?PwidapE2FZDmGyA2NRHhcFxtX4Ya52Q4Mej8SldTClUu6QyVDzvgLYrr+v5F?=
 =?us-ascii?Q?Xh3o9hweut2bYEnsXZjQ6bbEsQctqeBdG2IoP+Ci1kaTyki/UFRNhRh0l+fm?=
 =?us-ascii?Q?LgdiL2bJhJl3eVFzMssqI0ja4r8yP1dJEVg9hUCaztYuEeMpnSX2/wylfkvF?=
 =?us-ascii?Q?lHYLqXzoYNo4YBiyeeAJ9AImYSrNQadqNEx565Y6sXbf/L8QIyeT0Zov/PYu?=
 =?us-ascii?Q?FAAqfa5O2SWNDOz7hau18QiF9ea/+VAFB0nLJD0mCP3gI7uVCYRk/ZINxEfk?=
 =?us-ascii?Q?WwXyJJ8ApIt+ZfbV5u8+Nzn8KofLkcMiEpJ3Urmzy0r3WrdmgSVq76Q+HNQh?=
 =?us-ascii?Q?s3k5Mvdxvb+W4CWlEOODlz6CeC6NCsLqF3Chtwuq9i0FguKLAOIuXXluzpU0?=
 =?us-ascii?Q?Z9kP6NhxgevMPY99MewFa2BHILOXuZSXtaMrFrV45IcdODlZNcCD9XcvNDI7?=
 =?us-ascii?Q?bSnwpqoddkh22Vvaj3ZgNI0YuxQJjrFbNZIrysv4OqCwFUUiVYLlMov3zjiq?=
 =?us-ascii?Q?sZWVxs2YHN7E86oTI49FcX5b9g6gFgh8zCsdI9FE7ek5XZPI1m2YYVXbKX6c?=
 =?us-ascii?Q?lQglJzSDkWKzZAIpyHu4TWs/6jqAOmo+guNNy8Yqs0qkXJ84IHpnZHyXu1Qj?=
 =?us-ascii?Q?iy3grPkVQi/HyZ6tPOqB+QxejJ2QUuF9tuSGxqFN2JskNrgfkBPVj3A4r74/?=
 =?us-ascii?Q?hdZvTgUUc+LtEGXHp9XB9j2ScPRLoh1RwpuyVYfL5SJIYDqM6kih2t9FG7Wy?=
 =?us-ascii?Q?RMiyG04NSjoORS9z12ceVi0f8SvmGzkUcov13UtR1WpqeOEoV1bJO7ZH9X7N?=
 =?us-ascii?Q?hyP7C9bNUHbA90kNvmEnntfjHxbzydHaRqORsPcgTCmCUbblmeTV2pN4zjGu?=
 =?us-ascii?Q?ISy03lq2AjDwir0x4VBhtjjAr1aQSQm7POMKDXXi1y4li6zXzmArwRuAqdtH?=
 =?us-ascii?Q?Uf/+r24ez+RJj1Dz5e/pUcYnK1XvnWQUeoJkQmANlwq3TLcQSQ4O1RQRcQi1?=
 =?us-ascii?Q?GmFbsF19zEKSU0W2Zi9E7EqDdW600Y7e8pEOz56dDDA0PQWuxijlA9QVyzOp?=
 =?us-ascii?Q?eA=3D=3D?=
X-MS-Exchange-CrossTenant-Network-Message-Id: ba640d0a-5870-4119-6d41-08dc4b9d6bf8
X-MS-Exchange-CrossTenant-AuthSource: PH8PR11MB8107.namprd11.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 24 Mar 2024 00:57:47.4821
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: 46c98d88-e344-4ed4-8496-4ed7712e255d
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: sDYwBeN3nIluDMxtustRVVLFKJDcabeS8c3OngHqWhqtyPDZasckxm/xp72NjAWReapG0ZSciOnwdPhstYeRY8D+X8C0AIKug2ZP4q1W1yk=
X-MS-Exchange-Transport-CrossTenantHeadersStamped: DS0PR11MB6447
X-OriginatorOrg: intel.com

Matthew Wilcox wrote:
> On Fri, Mar 22, 2024 at 12:10:38PM -0700, Dan Williams wrote:
> > Peter Zijlstra wrote:
> > > So I despise all that RST stuff. It makes what should be trivially
> > > readable text into a trainwreck. We're coders, we use text editors to
> > > read comments.
> > 
> > Ok, I will rip out the RST stuff and just make this a standalone comment.
> 
> I would rather you ignored Peter's persistent whining about RST and
> kept the formatting.

Hmm, how about split the difference and teach scripts/kernel-doc to treat
Peter's preferred markup for a C code example as a synonym, i.e.
effectively a search and replace of a line with only:

	Ex.

..with:

	.. code-block:: c

..within a kernel-doc DOC: section?

Might be easier said the done as I stare down a pile of perl. Maybe a
perl wrangler will come along and take pity on this patch.