Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
Date:   Fri, 14 Jun 2019 18:24:22 +0200
From:   Greg Kroah-Hartman <gregkh@linuxfoundation.org>
To:     Jani Nikula <jani.nikula@linux.intel.com>
Cc:     Mauro Carvalho Chehab <mchehab+samsung@kernel.org>,
        Linux Doc Mailing List <linux-doc@vger.kernel.org>,
        Mauro Carvalho Chehab <mchehab@s-opensource.com>,
        Mauro Carvalho Chehab <mchehab@infradead.org>,
        linux-kernel@vger.kernel.org, Jonathan Corbet <corbet@lwn.net>
Subject: Re: [PATCH 05/14] scripts: add an script to parse the ABI files
Message-ID: <20190614162422.GA25680@kroah.com>
References: <cover.1560477540.git.mchehab+samsung@kernel.org>
 <196fb3c497546f923bf5d156c3fddbe74a4913bc.1560477540.git.mchehab+samsung@kernel.org>
 <87r27wuwc3.fsf@intel.com>
 <20190614133933.GA1076@kroah.com>
 <87lfy4uuzs.fsf@intel.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <87lfy4uuzs.fsf@intel.com>
User-Agent: Mutt/1.12.0 (2019-05-25)
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

On Fri, Jun 14, 2019 at 05:00:55PM +0300, Jani Nikula wrote:
> On Fri, 14 Jun 2019, Greg Kroah-Hartman <gregkh@linuxfoundation.org> wrote:
> > On Fri, Jun 14, 2019 at 04:31:56PM +0300, Jani Nikula wrote:
> >> On Thu, 13 Jun 2019, Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> >> > From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> >> >
> >> > Add a script to parse the Documentation/ABI files and produce
> >> > an output with all entries inside an ABI (sub)directory.
> >> >
> >> > Right now, it outputs its contents on ReST format. It shouldn't
> >> > be hard to make it produce other kind of outputs, since the ABI
> >> > file parser is implemented in separate than the output generator.
> >> 
> >> Hum, or just convert the ABI files to rst directly.
> >
> > And what would that look like?
> 
> That pretty much depends on the requirements we want to set on both the
> ABI source files and the generated output. Obviously the requirements
> can be conflicting; might be hard to produce fancy output if the input
> is very limited.
> 
> At the bare minimum, you could convert the files to contain
> reStructuredText field lists [1]. Add a colon at the start of the field
> name, and make sure field bodies (values) are not empty.
> 
> Conversion of a file selected at random; I've only added ":" and "N/A".

N/A should be allowed to just drop the line entirely, right?

And what does this end up looking like?

I also hate "flag days" where all of a chunk of stuff needs to be
converted into another style.  Also it doesn't deal with merges from the
100+ different trees that all end up adding stuff to this directory over
time (slowly though, unfortunately)

So ideally, I'd like to keep the original format if at all possible.
Having the tool here allows people to do nice things like search for a
specific file easily, or a device type, which is something that I know I
have wanted, and others have asked for in the past as well.

It also might allow us to find out where we are missing documentation, a
long-term goal of mine.

thanks,

greg k-h