linux-kernel - Re: [RFC PATCH v1 2/6] kernel-doc: replace kernel-doc perl parser with a pure python one (WIP)

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: <20170126115005.7bf0e4a6@lwn.net>
Date:   Thu, 26 Jan 2017 11:50:05 -0700
From:   Jonathan Corbet <corbet@....net>
To:     Markus Heiser <markus.heiser@...marit.de>
Cc:     Jani Nikula <jani.nikula@...el.com>,
        Mauro Carvalho Chehab <mchehab@...radead.org>,
        Daniel Vetter <daniel.vetter@...ll.ch>,
        Matthew Wilcox <mawilcox@...rosoft.com>,
        "linux-doc \@ vger . kernel . org List" <linux-doc@...r.kernel.org>,
        "linux-kernel \@ vger . kernel . org List" 
        <linux-kernel@...r.kernel.org>
Subject: Re: [RFC PATCH v1 2/6] kernel-doc: replace kernel-doc perl parser
 with a pure python one (WIP)

On Wed, 25 Jan 2017 20:07:47 +0100
Markus Heiser <markus.heiser@...marit.de> wrote:

> So, what I mean is, the new parser has to generate a complete different reST
> output and thats why we can't compare the perl parser with python one on a reST
> basis ... and if reST is different, HTML is different :(
> 
> So we do not have any chance to track regression when switching from
> the old to the new parser.
> 
> Thats are my thoughts on this topic, may be you have a solution for this?

The solution, I think, is as has been described by others in the thread.
I'll make a try at it now :)

The objectives in a patch set are something like this:

 - Replace the kernel-doc utility with one that is easier to maintain and
   enhance.

 - Add various enhancements (man pages, linting, better output, better
   parsing) to the docs build system.

What everybody is complaining about here is that all of that stuff is
being thrown in together into a single patch set.  We don't do things that
way because long experience says we'll create a mess that takes a long
time to straighten out again.

As I said before, I'm very much amenable to the idea of replacing
kernel-doc with one that is easier to work with.  I haven't yet had the
time to look closely enough at yours to have an opinion on whether it does
that or not.  But, assuming it does, the proper way to make this change is
to provide a new kerneldoc that behaves as closely to the old one as
possible, with an absolute minimum of output changes.

Doing it that way probably seems like a pretty annoying request.  But it
lets us validate its basic mechanics and be confident that we won't break
the docs build in weird ways.  It also lets us evaluate the question of
whether the replacement has merit in its own right, independent of any
other change we want to make.  Give me a new kerneldoc that passes those
tests, and I'll happily merge it.  (I have some sympathy with the idea
that we should look into other parsers, but I would not hold up a new
kerneldoc that passed those tests on this basis alone.)

*Then* we can start adding the other stuff, which, from a first look,
appears to be stuff that we very much want to have.  Each one of those,
too, should stand alone and pass muster on its own merits.  Changes
presented in this way could be merged in the same development cycle if
they are ready, but we need to be able to evaluate each one separately.

Does this make sense?  We all really appreciate the work you're doing
here, we're just asking that it be done in an evolutionary manner so we
can evaluate it properly.

Thanks,

jon