Re: [PATCH 12/14] doc-rst: add ABI documentation to the admin-guide book

[Greg Kroah-Hartman]

On Mon, Jun 17, 2019 at 03:36:17PM +0300, Jani Nikula wrote:
> On Fri, 14 Jun 2019, Mauro Carvalho Chehab <mchehab+samsung@xxxxxxxxxx> wrote:
> > Em Fri, 14 Jun 2019 16:06:03 +0200
> > Greg Kroah-Hartman <gregkh@xxxxxxxxxxxxxxxxxxx> escreveu:
> >
> >> On Fri, Jun 14, 2019 at 04:42:20PM +0300, Jani Nikula wrote:
> >> > 2) Have the python extension read the ABI files directly, without an
> >> >    extra pipeline.  
> >> 
> >> He who writes the script, get's to dictate the language of the script :)
> 
> The point is, it's an extension to a python based tool, written in perl,
> using pipes for communication, and losing any advantages of integrating
> with the tool it's extending.
> 
> I doubt you'd want to see system() to be used to subsequently extend the
> perl tool.
> 
> I think it's just sad to see the documentation system slowly drift
> further away from the ideals we had, and towards the old ways we worked
> so hard to fix.

What are those ideals?

I thought the goal was to be able to write documentation in a as much
as a normal text file as possible and have automation turn those files
into "pretty" documentation that we can all use.

And I think that fits with the way this patch set goes, right?  We are
not on a quest for purity of scripts to generate the documentation at
the expense of having to force hundreds, or thousands, of developers to
change their ways, or to force a "flag day" conversion of existing
documentation resulting in a huge merge mess.

So, we are stuck with the current structure that I totally made up for
Documentation/ABI/.  Turns out it is almost parsable, as Mauro's tool
shows.  His tool also validates the existing text, which is great, and
has caused fixes for it.

If someone wants to write that tool in some other language, like python,
wonderful, I have no objection, but as it is, this is a useful tool
already, allowing us to validate, and search, existing documentation
entries that we have never been able to do before.  It also provides an
output that can be turned into pretty html/pdf/whatever files by other
tools in the pipeline, a totally bonus benefit.

So what is going backwards here?

Maybe the processing pipeline isn't as nice as you would like, but
remember to view this from a normal developer's point of view, not a
documentation pipeline developer's point of view please.

So, in short, my requirements are:
	- keep Documentation/ABI/ file formats as close as possible to
	  what we have today, preventing any flag-day issues or merge
	  problems
	- be able to query and validate Documentation/ABI/
	- be able to turn Documentation/ABI into pretty documentation.

If you object to the mechanics of the last requirement here, I don't
object either, provide something else that works better.  But don't
throw away the whole thing just because you don't like how things are
hooked up here.

I'm going to go apply most of the rest of these patches to my
driver-core tree, stopping at the "hook it up to the kernel
documentation" point.  Is that ok?

thanks,

greg k-h