linux-kernel - Re: [PATCH] scripts/kernel-doc: remove an obscure logic from kernel-doc

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: <87wmdnm0kh.fsf@trenco.lwn.net>
Date: Tue, 18 Feb 2025 13:59:10 -0700
From: Jonathan Corbet <corbet@....net>
To: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
Cc: Linux Doc Mailing List <linux-doc@...r.kernel.org>,
 linux-kernel@...r.kernel.org
Subject: Re: [PATCH] scripts/kernel-doc: remove an obscure logic from
 kernel-doc

Mauro Carvalho Chehab <mchehab+huawei@...nel.org> writes:

> With regards to the Python transition, since our Makefile allows
> switching to a different script since ever[1], I'm playing with 
> the idea of sending a patch series with:
>
> Patch 1: 
>   - drops Sphinx version check from both kerneldoc 
>     (-sphinx-version parameter) and the corresponding Sphinx extension;
>
> patch 2: 
>   - renames kerneldoc to kerneldoc.pl
>   - creates a symlink:
> 	kerneldoc.pl -> kerneldoc
>
> patch 3:
>   - adds kerneldoc.py:
>
> patch 4:
>   - add info messages on both versions related to the transition,
>     and instructions about using KERNELDOC=<script> makefile and ask
>     people to report eventual regressions with new script.
>
> patch 5:
>   - change kerneldoc symlink to point to kerneldoc.py
>
> We can then keep both for maybe one Kernel cycle and see how it goes,
> stop accepting patches to the Perl version, in favor of doing the needed
> changes at the Python one.
>
> If everything goes well, we can remove the venerable Perl version on the 
> upcoming merge window, and change the Sphinx extension to use the Python
> classes directly instead of running an external executable code.
>
> What do you think?

Seems like a fine plan in general.  I wonder if we might want to keep
the old kernel-doc a bit longer just in case, but we can decide that as
we go.

> I'm in doubt if I should split the Kernel classes for the Python version
> into a scripts/lib/kdoc directory on this series or doing such change
> only after we drop the Perl version.
>
> Keeping it on a single file helps to do more complex code adjustments 
> on a single place, specially if we end renaming/shifting stuff[2].

Do whatever makes it easiest for you at this point, I'd say.

> On a separate but related issue, perhaps we should start talking about
> coding style. We don't have anything defined at the Kernel, and
> different scripts follow different conventions (or most likely
> don't follow any convention at all). We should probably think having 
> something defined in the future.

I've generally tried to stick to something that looks as close to the C
coding style as possible.  Formalizing that might not be a bad idea at
all.

jon